plain-forge 1.0.23 → 1.0.24-next.019bba8

package/forge/skills/analyze-if-func-spec-too-complex/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 
 # Analyze If Functional Spec Is Too Complex
 
-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.
 
 ## Why This Matters
 
@@ -50,20 +50,25 @@ Too complex:
 ```plain
 ***functional specs***
 
-- A :User: can create, edit, delete, and archive :Task: items, with validation on all fields and confirmation dialogs for destructive actions.
+# manage-tasks
+A :User: can create, edit, delete, and archive :Task: items, with validation on all fields and confirmation dialogs for destructive actions.
 ```
 
 Acceptable (one behavior each):
 ```plain
 ***functional specs***
 
-- A :User: can create :Task:. Only valid :Task: items can be added.
+# create-task
+A :User: can create :Task:. Only valid :Task: items can be added.
 
-- A :User: can edit :Task:.
+# edit-task
+A :User: can edit :Task:.
 
-- A :User: can delete :Task:.
+# delete-task
+A :User: can delete :Task:.
 
-- A :User: can archive :Task:.
+# archive-task
+A :User: can archive :Task:.
 
 ```
 
@@ -84,19 +89,23 @@ Too complex:
 ```plain
 ***functional specs***
 
-- :Order: processing depends on :OrderType:. Standard orders are validated and stored. Express orders skip validation and are queued for immediate dispatch. Bulk orders are split into sub-orders of 100 items each, validated individually, and processed in parallel with progress tracking.
+# process-order
+:Order: processing depends on :OrderType:. Standard orders are validated and stored. Express orders skip validation and are queued for immediate dispatch. Bulk orders are split into sub-orders of 100 items each, validated individually, and processed in parallel with progress tracking.
 ```
 
 Acceptable (separate the modes):
 ```plain
 ***functional specs***
 
-- A standard :Order: is validated and stored.
+# process-standard-order
+A standard :Order: is validated and stored.
 
-- An express :Order: is queued for immediate dispatch without validation.
+# process-express-order
+An express :Order: is queued for immediate dispatch without validation.
 
-- A bulk :Order: is split into sub-orders of 100 items each.
-  - Each sub-order is processed individually.
+# split-bulk-order
+A bulk :Order: is split into sub-orders of 100 items each.
+- Each sub-order is processed individually.
 ```
 
 ### 4. Cross-Cutting Concerns
@@ -107,17 +116,21 @@ Too complex:
 ```plain
 ***functional specs***
 
-- :Resource: items are fetched from the external API with pagination support, retry on transient errors with exponential backoff, caching for 5 minutes, and logging of all API calls.
+# fetch-resources
+:Resource: items are fetched from the external API with pagination support, retry on transient errors with exponential backoff, caching for 5 minutes, and logging of all API calls.
 ```
 
 Acceptable (separate concerns):
 ```plain
 ***functional specs***
-- :Resource: items are fetched from the external API.
+# fetch-resources
+:Resource: items are fetched from the external API.
 
-- :Resource: items are fetched from the external API in pages.
+# fetch-resources-paged
+:Resource: items are fetched from the external API in pages.
 
-- Fetching :Resource: items is retried on transient errors using exponential backoff.
+# retry-resource-fetch
+Fetching :Resource: items is retried on transient errors using exponential backoff.
 ```
 
 ### 5. UI Complexity
@@ -128,18 +141,22 @@ Too complex:
 ```plain
 ***functional specs***
 
-- The dashboard shows :User: profile, recent :Task: items in a sortable table, a notification bell with unread count, and a sidebar with navigation links that highlights the active page.
+# dashboard
+The dashboard shows :User: profile, recent :Task: items in a sortable table, a notification bell with unread count, and a sidebar with navigation links that highlights the active page.
 ```
 
 Acceptable (build incrementally):
 ```plain
 ***functional specs***
 
-- A dashboard page is shown for :User:.
+# dashboard-page
+A dashboard page is shown for :User:.
 
-- Recent :Task: items are shown in a sortable table on the dashboard.
+# dashboard-recent-tasks
+Recent :Task: items are shown in a sortable table on the dashboard.
 
-- A notification indicator with the unread count is shown on the dashboard.
+# dashboard-notifications
+A notification indicator with the unread count is shown on the dashboard.
 ```
 
 ### 6. Data Transformation Complexity
@@ -157,18 +174,21 @@ Too complex (builds the component and uses it in one spec):
 ```plain
 ***functional specs***
 
-- A :Report: is exported to PDF, laying out multi-page tables with repeating headers and page numbers, and charts rendered from :Report: data.
+# export-report-pdf
+A :Report: is exported to PDF, laying out multi-page tables with repeating headers and page numbers, and charts rendered from :Report: data.
 ```
 
 Acceptable (component in its own spec, then referenced):
 ```plain
 ***functional specs***
 
-- :PdfRenderer: lays out multi-page tables from structured content.
-  - Table headers repeat at the top of each page.
-  - Each page shows its page number.
+# pdf-renderer-tables
+:PdfRenderer: lays out multi-page tables from structured content.
+- Table headers repeat at the top of each page.
+- Each page shows its page number.
 
-- A :Report: is exported to PDF using :PdfRenderer:, embedding charts rendered from :Report: data.
+# export-report-pdf
+A :Report: is exported to PDF using :PdfRenderer:, embedding charts rendered from :Report: data.
 ```
 
 When this indicator fires, the fix is `break-down-func-spec` Strategy 6 — extract the component into its own earlier spec and reference it.

package/forge/skills/break-down-func-spec/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 
 # Break Down 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.
 
 ## When to Use
 
@@ -36,12 +36,13 @@ The functional spec to break down, plus the full `.plain` file it belongs to.
    - Independently meaningful (makes sense on its own with previous specs as context)
    - Self-contained (does not require a later spec to be useful)
    - Within the 200 LOC limit
-5. **Draft the replacement specs** — write the smaller specs in chronological order. The first replacement spec typically sets up the foundation, and subsequent ones layer behavior on top.
+5. **Draft the replacement specs** — write the smaller specs in chronological order, each with its own func-id per `semantic-ids.md`; the replacement that keeps the original's main behavior may keep the original's func-id. The first replacement spec typically sets up the foundation, and subsequent ones layer behavior on top.
 6. **Verify functional completeness** — this is critical. The replacement specs taken together must cover **100% of the functionality** described in the original spec. Walk through every behavior, condition, and detail in the original and confirm it appears in exactly one of the replacement specs. Nothing may be lost, weakened, or left implicit. If any functionality from the original is missing, add it to the appropriate replacement spec or create an additional one.
 7. **Verify each replacement spec** — run `analyze-if-func-spec-too-complex` on each to confirm it fits within the limit.
 8. **Check for conflicts** — run `analyze-func-specs` **once** with the full set of replacement specs plus every existing spec in the file and its `requires` chain. The batched analyzer reports every conflicting pair (replacement × existing and replacement × replacement) in one call — do not loop over pairs. Resolve each reported pair with `resolve-spec-conflict`, then re-run `analyze-func-specs` over the touched set until the verdict is `COMPATIBLE`.
-9. **Replace in the file** — remove the original spec and insert the replacement specs in its position, preserving chronological order.
-10. **Read the file again** to confirm correct placement and syntax.
+9. **Replace in the file** — remove the original functionality (heading and body) and insert the replacement functionalities, each as a `# <func-id>` heading with its body, in its position, preserving chronological order.
+10. **Bring the test plain files in step** — invoke `add-test-scenarios` for each replacement functionality. It moves every scenario of the original's test plain file to the replacement it tests, writes scenarios for outcomes that have none, and deletes the original's file when its func-id no longer exists.
+11. **Read the file again** to confirm correct placement and syntax.
 
 ## Splitting Strategies
 
@@ -53,18 +54,22 @@ If the spec bundles multiple independently testable actions, split each into its
 ```plain
 ***functional specs***
 
-- A :User: can create, edit, and delete :Recipe: items, with validation on all fields.
+# manage-recipes
+A :User: can create, edit, and delete :Recipe: items, with validation on all fields.
 ```
 
 **After:**
 ```plain
 ***functional specs***
 
-- A :User: can create a :Recipe:. Only valid :Recipe: items can be created.
+# create-recipe
+A :User: can create a :Recipe:. Only valid :Recipe: items can be created.
 
-- A :User: can edit an existing :Recipe:. Validation rules apply to the edited fields.
+# edit-recipe
+A :User: can edit an existing :Recipe:. Validation rules apply to the edited fields.
 
-- A :User: can delete a :Recipe:.
+# delete-recipe
+A :User: can delete a :Recipe:.
 ```
 
 ### Strategy 2: Separate Setup from Behavior
@@ -75,18 +80,22 @@ If the spec introduces a new construct and immediately defines complex behavior
 ```plain
 ***functional specs***
 
-- The :MealPlan: screen displays a weekly grid of :Slot: items, allows drag-and-drop reordering, and shows nutritional totals per day.
+# meal-plan-screen
+The :MealPlan: screen displays a weekly grid of :Slot: items, allows drag-and-drop reordering, and shows nutritional totals per day.
 ```
 
 **After:**
 ```plain
 ***functional specs***
 
-- The :MealPlan: screen displays a weekly grid of :Slot: items.
+# meal-plan-grid
+The :MealPlan: screen displays a weekly grid of :Slot: items.
 
-- A :User: can reorder :Slot: items within a day on the :MealPlan: screen using drag-and-drop.
+# reorder-slots
+A :User: can reorder :Slot: items within a day on the :MealPlan: screen using drag-and-drop.
 
-- The :MealPlan: screen displays nutritional totals for each day.
+# daily-nutrition-totals
+The :MealPlan: screen displays nutritional totals for each day.
 ```
 
 ### Strategy 3: Separate Core Logic from Cross-Cutting Concerns
@@ -97,18 +106,22 @@ If the spec mixes primary functionality with error handling, retries, caching, p
 ```plain
 ***functional specs***
 
-- :Ingredient: data is fetched from the external API with pagination, retry on transient errors, and caching for 10 minutes.
+# fetch-ingredients
+:Ingredient: data is fetched from the external API with pagination, retry on transient errors, and caching for 10 minutes.
 ```
 
 **After:**
 ```plain
 ***functional specs***
 
-- :Ingredient: data is fetched from the external API.
+# fetch-ingredients
+:Ingredient: data is fetched from the external API.
 
-- :Ingredient: data is fetched from the external API in pages.
+# fetch-ingredients-paged
+:Ingredient: data is fetched from the external API in pages.
 
-- Fetching :Ingredient: data is retried on transient errors.
+# retry-ingredient-fetch
+Fetching :Ingredient: data is retried on transient errors.
 ```
 
 ### Strategy 4: Separate Conditional Paths
@@ -119,20 +132,24 @@ If the spec describes different modes or branches, give each its own spec.
 ```plain
 ***functional specs***
 
-- :MealPlan: generation depends on :DietType:. Standard plans use round-robin assignment. Restrictive plans filter out excluded ingredients first, then apply round-robin. Custom plans allow manual slot-by-slot selection.
+# generate-meal-plan
+:MealPlan: generation depends on :DietType:. Standard plans use round-robin assignment. Restrictive plans filter out excluded ingredients first, then apply round-robin. Custom plans allow manual slot-by-slot selection.
 ```
 
 **After:**
 ```plain
 ***functional specs***
 
-- A standard :MealPlan: is generated using round-robin :Recipe: assignment.
+# generate-standard-plan
+A standard :MealPlan: is generated using round-robin :Recipe: assignment.
 
-- A restrictive :MealPlan: is generated.
-  - Excluded :Ingredient: items are filtered out first.
-  - Round-robin :Recipe: assignment is then applied.
+# generate-restrictive-plan
+A restrictive :MealPlan: is generated.
+- Excluded :Ingredient: items are filtered out first.
+- Round-robin :Recipe: assignment is then applied.
 
-- A :User: can manually assign :Recipe: items to :Slot: items for a custom :MealPlan:.
+# assign-custom-plan
+A :User: can manually assign :Recipe: items to :Slot: items for a custom :MealPlan:.
 ```
 
 ### Strategy 5: Build UI Incrementally
@@ -143,18 +160,22 @@ If the spec describes a full screen, split into layout + individual interactive
 ```plain
 ***functional specs***
 
-- The :Dashboard: screen shows a summary card with stats, a scrollable list of recent :MealPlan: items, a floating action button to create a new plan, and a bottom navigation bar.
+# dashboard-screen
+The :Dashboard: screen shows a summary card with stats, a scrollable list of recent :MealPlan: items, a floating action button to create a new plan, and a bottom navigation bar.
 ```
 
 **After:**
 ```plain
 ***functional specs***
 
-- The :Dashboard: screen shows a summary card with :MealFrameStats:.
+# dashboard-summary-card
+The :Dashboard: screen shows a summary card with :MealFrameStats:.
 
-- The :Dashboard: screen shows a scrollable list of recent :MealPlan: items.
+# dashboard-recent-plans
+The :Dashboard: screen shows a scrollable list of recent :MealPlan: items.
 
-- The :Dashboard: screen includes a button to create a new :MealPlan:.
+# dashboard-new-plan-button
+The :Dashboard: screen includes a button to create a new :MealPlan:.
 ```
 
 ### Strategy 6: Extract a Reusable Technical Component
@@ -167,18 +188,21 @@ Define the component concept in `***definitions***` (via `add-concept`) before t
 ```plain
 ***functional specs***
 
-- A :Report: is exported to PDF, laying out multi-page tables with repeating headers, page numbers, and charts rendered from :Report: data.
+# export-report-pdf
+A :Report: is exported to PDF, laying out multi-page tables with repeating headers, page numbers, and charts rendered from :Report: data.
 ```
 
 **After:**
 ```plain
 ***functional specs***
 
-- :PdfRenderer: lays out multi-page tables from structured content.
-  - Table headers repeat at the top of each page.
-  - Each page shows its page number.
+# pdf-renderer-tables
+:PdfRenderer: lays out multi-page tables from structured content.
+- Table headers repeat at the top of each page.
+- Each page shows its page number.
 
-- A :Report: is exported to PDF using :PdfRenderer:, embedding charts rendered from :Report: data.
+# export-report-pdf
+A :Report: is exported to PDF using :PdfRenderer:, embedding charts rendered from :Report: data.
 ```
 
 The extracted component spec and the rewritten original must together still cover 100% of the original functionality (step 6): the original must **reference** the component, never re-describe it. Keep the component's technology and architecture choices in `***implementation reqs***`, not in the functional spec. If the component is a self-contained subsystem or will be reused across modules, promote it to its own module with `create-requires-module` / `refactor-module` instead of a sibling spec.
@@ -187,7 +211,7 @@ The extracted component spec and the rewritten original must together still cove
 
 The replacement specs take the position of the original spec. Earlier specs remain unchanged. The first replacement spec should make sense given only the specs above it. Each subsequent replacement spec can reference behavior from the ones before it.
 
-If the original spec had acceptance tests, redistribute them to the most appropriate replacement spec — or drop tests that no longer apply to a single smaller spec and rewrite them.
+The original functionality's test plain file is split the same way: each scenario moves to the replacement functionality it tests, a scenario that no longer fits one replacement is rewritten, and each replacement ends with at least one conformance scenario when conformance tests are enabled (see `add-test-scenarios`).
 
 ## Validation Checklist
 
@@ -203,4 +227,4 @@ If the original spec had acceptance tests, redistribute them to the most appropr
 - [ ] Replacement specs are language-agnostic
 - [ ] Replacement specs trimmed per `concise-specs.md` — a split is not a licence to re-add prose
 - [ ] All external interfaces remain explicit
-- [ ] Acceptance tests (if any) have been redistributed or rewritten
+- [ ] Test plain files follow the split: one per replacement functionality, every original scenario moved or rewritten, none bound to a func-id that no longer exists

package/forge/skills/check-plain-env/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 
 # Check Plain Env
 
-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.
 
 This skill answers one question: **does the host machine have everything the ***plain project needs to render and test?** It reads the project, derives the requirement list, probes the machine, and returns a report. It never installs anything itself — that decision belongs to the user.
 
@@ -43,7 +43,7 @@ The skill is a **derive → probe → report** pass. It does not stop at the fir
 ### Step 1 — Inventory the project
 
 1. **Detect the host OS** first. Run `uname -s 2>/dev/null || echo "$OS"`. Use the result to (a) pick the right script extensions to inspect (`.sh` vs `.ps1`) and (b) pick the right install commands later (Homebrew, apt, dnf, pacman, choco, scoop, winget).
-2. **List every `.plain` file** in the repo root and in any subdirectory that contains them. Note which are top modules (not `requires`-ed by anything) and which are import modules (under `template/`).
+2. **List every `.plain` file** in the repo root and in any subdirectory that contains them. Note which are top modules (not `requires`-ed by any other module) and which are import modules (under `template/`).
 3. **List every `config.yaml`** in the repo and read each one. Note the `*-script` keys it sets and the values they point at.
 4. **List every script under `test_scripts/`** (both `.sh` and `.ps1` — projects can ship both).
 5. **List every file under `resources/`** if the directory exists. Schemas and protocol files there often imply running services (e.g. a Postgres `.sql` schema implies a Postgres server).

package/forge/skills/consolidate-concepts/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Consolidate Concepts
 
-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
 
@@ -72,7 +72,7 @@ For each affected module, determine the frontmatter changes:
 |--------|------|
 | Add the new import to `import` list | Module does not already import the target |
 | Remove concepts from `exported_concepts` | Concepts that were exported only to share definitions — now handled by the import |
-| Keep concepts in `exported_concepts` | Concepts that downstream `requires` modules still need via export (because those downstream modules do not import the new template) |
+| Keep concepts in `exported_concepts` | Concepts that downstream modules still need via export (because those downstream modules do not import the new template) |
 
 **Important:** `import` provides definitions to the importing module. `exported_concepts` on a `requires` module provides concepts to downstream modules in the build chain. If a downstream module will now `import` the shared template directly, the concept can be removed from `exported_concepts`. If a downstream module does **not** import the template, the concept must remain exported.
 
@@ -112,7 +112,7 @@ For each module that had concepts moved out:
 
 ### 3c. Update downstream modules (if applicable)
 
-If concepts were removed from a module's `exported_concepts` and downstream `requires` modules relied on them:
+If concepts were removed from a module's `exported_concepts` and downstream modules relied on them:
 1. Add the new import to the downstream module's `import` list so it gets the concepts directly.
 2. Verify the downstream module's specs can still resolve all concept references.
 
@@ -141,7 +141,7 @@ For every affected module (source modules, downstream modules, and the import mo
 - [ ] No `***functional specs***` were modified in any module
 - [ ] No `***implementation reqs***` were modified in any module
 - [ ] No `***test reqs***` were modified in any module
-- [ ] No `***acceptance tests***` were modified in any module
+- [ ] No test plain file was modified
 
 ### 4e. Structural validation
 
@@ -165,7 +165,7 @@ Read each modified `.plain` file in full and present the changes to the user for
 ### Moving a concept that is only used locally
 If a concept is only referenced within a single module, consolidating it into a shared import adds unnecessary coupling. Keep it local.
 
-### Forgetting to update downstream requires modules
+### Forgetting to update downstream modules
 When a concept is removed from `exported_concepts`, any module that `requires` the source module and references that concept will break — unless it now imports the shared template. Always trace the full dependency chain.
 
 ### Breaking concept ordering
@@ -175,7 +175,7 @@ Concepts in the import module must be topologically ordered. If `:Meal:` referen
 An import module cannot `import` a module that directly or indirectly imports it back. If the shared concepts reference concepts from an existing template, the new import module should itself import that template — not the other way around.
 
 ### Removing concepts from exported_concepts prematurely
-Only remove a concept from `exported_concepts` if **every** downstream `requires` module that needs it will now get it via `import`. If even one downstream module does not import the shared template, the export must stay.
+Only remove a concept from `exported_concepts` if **every** downstream module that needs it will now get it via `import`. If even one downstream module does not import the shared template, the export must stay.
 
 ## Validation Checklist
 
@@ -186,8 +186,8 @@ Only remove a concept from `exported_concepts` if **every** downstream `requires
 - [ ] Every affected module's `import` list includes the target import module
 - [ ] `exported_concepts` updated correctly — no missing exports, no unnecessary exports
 - [ ] All concept references in all affected modules resolve correctly
-- [ ] No functional specs, implementation reqs, test reqs, or acceptance tests were modified
+- [ ] No functional specs, implementation reqs, test reqs, or test plain files were modified
 - [ ] Import module is in `template/` and has no functional specs or requires
 - [ ] No circular imports introduced
-- [ ] Downstream requires modules updated if needed
+- [ ] Downstream modules updated if needed
 - [ ] User approved the final result

package/forge/skills/create-import-module/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Create Import Module
 
-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.
 
 ## What an Import Module Is
 

package/forge/skills/create-requires-module/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Create Requires Module
 
-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.
 
 ## What Requires Does
 
@@ -19,6 +19,7 @@ When this module is rendered:
 - The required module's generated code (`plain_modules/<required_module>/code`) is copied as the starting point.
 - The `***functional specs***` of the required module **and all its ancestors** become visible as **previous functional specs**.
 - Of the required module's definitions, only the concepts in its `exported_concepts` are visible, each with its full definition text. Export visibility is **not** transitive — to see an ancestor's exports, list that ancestor in `requires` too.
+- The required module's test plain files stay with the required module. The new module gets its own test plain files, one per functionality it adds (see `test-plain-files.md`).
 
 All modules connected by `requires` form a single tree with a common root. **Diamond joins are prohibited**: multiple `requires` entries must lie on one root-to-tip ancestor path. The deepest entry is the attachment point; the other entries exist only to make those ancestors' exports visible.
 
@@ -34,7 +35,7 @@ If you only need shared definitions and reqs (no functional specs, no generated
 2. **Create the `.plain` file at the repository root** with YAML frontmatter containing the `requires` field. Modules with functional specs live at the root, not in `template/`.
 3. **Review the functional specs of the whole ancestor chain** — they will be treated as previous requirements. Your new functional specs must not conflict with any of them.
 4. **Review each listed module's `exported_concepts`** — only those concepts are available to reference; an ancestor's exports require listing that ancestor.
-5. **Add module-specific content** — definitions, implementation reqs, test reqs, and functional specs unique to this module.
+5. **Add module-specific content** — definitions, implementation reqs, test reqs, and functional specs unique to this module. Add every functional spec through `add-functional-spec` or `add-functional-specs`, which also create its test plain file.
 6. **Check for conflicts** between your new functional specs and any spec in the ancestor chain.
 
 ## Format
@@ -56,7 +57,8 @@ description: Extended module that builds on base_module
 
 ***functional specs***
 
-- :NewFeature: is available.
+# new-feature
+:NewFeature: is available.
 ```
 
 A module can use both `requires` and `import` together. `requires` points to other root-level modules; `import` resolves from the default `template/` directory (no prefix needed).
@@ -106,5 +108,6 @@ The current module may or may not be functionally related to the required module
 - [ ] Every listed module's `exported_concepts` provide the concepts you need
 - [ ] New functional specs do not conflict with any spec in the ancestor chain
 - [ ] Module has at least one functional spec and one implementation req
+- [ ] Every functional spec has its test plain file
 - [ ] Both `requires` and `import` are used correctly (not mixed up)
 - [ ] YAML frontmatter is correctly formatted between `---` markers

package/forge/skills/debug-specs/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 
 # Debug 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
 
@@ -30,7 +30,7 @@ Generated code in `plain_modules/<module>/code/` and `plain_modules/<module>/tes
 
 ## Phase 1 — Understand the Context
 
-1. **Read the `.plain` file(s)** for the module — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read `import` and `requires` chains.
+1. **Read the `.plain` file(s)** for the module — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read `import` and `requires` chains, and the module's test plain files.
 2. **Read the user's observation carefully.** Rephrase it back to confirm understanding. Identify:
    - What is the expected behavior?
    - What is the actual behavior?
@@ -60,13 +60,13 @@ For each relevant file:
 ### 2c. Check conformance tests and unit tests (if relevant)
 
 If the bug manifests as a test failure:
-1. Read the failing test — conformance tests in `plain_modules/<module_name>/tests/<functionality>/`, unit tests inside `plain_modules/<module_name>/code/`.
+1. Read the failing test — conformance tests in `plain_modules/<module_name>/tests/<func-id>/`, each labelled with the scenario-id it implements, unit tests inside `plain_modules/<module_name>/code/`.
 2. Understand what the test expects vs. what the implementation does.
 3. Determine whether the test expectation is correct (matches the spec) or incorrect (doesn't match the spec).
 
 ## Phase 3 — Diagnose the Root Cause
 
-Trace the issue from the generated code back to the specs. There are five possible root causes — determine which one applies **before** making changes:
+Trace the issue from the generated code back to the specs. There are six possible root causes — determine which one applies **before** making changes:
 
 | Root Cause | Symptom | Fix |
 |------------|---------|-----|
@@ -74,6 +74,7 @@ Trace the issue from the generated code back to the specs. There are five possib
 | **Missing spec** | The desired behavior is not covered by any spec. The renderer had no guidance and either did nothing or made an arbitrary choice. | Add a new functional spec using the `add-functional-spec` skill. |
 | **Conflicting specs** | Two specs contradict each other, causing the renderer to produce inconsistent behavior. | Use the `resolve-spec-conflict` skill. |
 | **Incorrect spec** | The spec explicitly describes the wrong behavior. The renderer implemented it faithfully, but the spec itself is wrong. | Rewrite the spec to describe the correct behavior. |
+| **Incorrect scenario** | The spec is correct and the code matches it, but a scenario in the test plain file expects an outcome the spec does not state, or misses one it states. | Fix the scenario with `add-test-scenarios`. |
 | **Missing implementation req** | The spec is correct, but the implementation req doesn't provide enough guidance for the renderer to produce the right code (e.g., missing library, missing architectural constraint, missing platform detail). | Add or update the implementation req using the `add-implementation-requirement` skill. |
 
 ### How to diagnose
@@ -85,7 +86,9 @@ Trace the issue from the generated code back to the specs. There are five possib
 2. **Check for conflicts.** Could another spec be overriding or contradicting this behavior?
    - Read all functional specs that touch the same concepts.
    - If two specs are in tension → **conflicting specs**.
-3. **Check implementation reqs.** Is the renderer missing guidance on how to implement correctly?
+3. **Check the scenario.** When a conformance or acceptance test fails, find its scenario by the scenario-id in the test name and compare it with the spec.
+   - If the scenario contradicts or extends the spec → **incorrect scenario**.
+4. **Check implementation reqs.** Is the renderer missing guidance on how to implement correctly?
    - Does the implementation req specify the right library, pattern, or constraint?
    - If a platform-specific or framework-specific detail is missing → **missing implementation req**.
 
@@ -95,10 +98,11 @@ Apply the fix based on the diagnosed root cause. Use the appropriate skill:
 
 | Root Cause | Skill to Use |
 |------------|-------------|
-| Ambiguous spec | Edit the spec inline — add sub-bullets or reword for clarity |
+| Ambiguous spec | Edit the spec inline — add detail under the statement line or reword for clarity |
 | Missing spec | `add-functional-spec` |
 | Conflicting specs | `resolve-spec-conflict` |
 | Incorrect spec | Edit the spec inline — rewrite the incorrect part |
+| Incorrect scenario | `add-test-scenarios` |
 | Missing implementation req | `add-implementation-requirement` |
 
 ### Fix guidelines
@@ -107,6 +111,7 @@ Apply the fix based on the diagnosed root cause. Use the appropriate skill:
 - **Preserve chronological order.** If adding a new spec, place it correctly relative to existing specs.
 - **Stay language-agnostic.** Functional specs describe behavior, not implementation. Platform-specific guidance belongs in implementation reqs.
 - **Respect the 200 LOC limit.** If a fix makes a spec too complex, use `break-down-func-spec` to split it.
+- **Keep the test plain file in step.** After changing a functional spec, invoke `add-test-scenarios` for it so its scenarios still follow from the spec.
 - **Check for new conflicts.** After editing, verify the fix doesn't conflict with other specs by running `analyze-func-specs` once with the edited spec(s) plus every existing spec that touches the same concepts. The batched analyzer reports all conflicting pairs in a single call; resolve each with `resolve-spec-conflict`.
 
 ## Phase 5 — Verify and Report
@@ -148,7 +153,7 @@ A test is failing. Use the test as the entry point.
 ```
 Read failing test → Understand what it expects → Read the implementation →
 Determine if the test or the implementation is wrong → Trace back to the spec →
-Fix the spec (or test reqs/acceptance tests if the test itself is wrong)
+Fix the spec (or the test reqs / the scenario in the test plain file if the test itself is wrong)
 ```
 
 ### Strategy 4: Differential
@@ -179,11 +184,12 @@ A spec fix may affect other specs that reference the same concepts. Always check
 
 - [ ] User's observation is clearly understood (expected vs. actual behavior)
 - [ ] Generated code has been read to understand the current implementation
-- [ ] Root cause is diagnosed (ambiguous / missing / conflicting / incorrect / missing impl req)
+- [ ] Root cause is diagnosed (ambiguous / missing / conflicting / incorrect / incorrect scenario / missing impl req)
 - [ ] Fix is applied in the `.plain` file(s) only — no generated code modified
 - [ ] Fix is minimal and targeted to the observed bug
 - [ ] Fix does not introduce new conflicts with existing specs
 - [ ] Modified specs respect the 200 LOC limit
 - [ ] Modified specs remain language-agnostic
 - [ ] Chronological ordering is preserved
+- [ ] Test plain file of every changed functionality brought in step via `add-test-scenarios`
 - [ ] Summary of findings and fix presented to the user

package/forge/skills/forge-plain/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 
 # Forge Plain
 
-Always invoke the `load-plain-reference` skill first to load the `***plain` syntax rules — but only if it hasn't been loaded yet this session.
+**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.
 
 ## Role
 
@@ -54,7 +54,7 @@ Use the dedicated edit skills for every write — never hand-author a `***plain`
 
 ## Review loop
 
-After each authoring step, review **only what just changed** — never re-review the whole file. Pick the single most relevant snippet (one concept, one functional spec, the module frontmatter, one requirement, one acceptance test, one script change, one `config.yaml` entry) and embed it directly in the `AskUserQuestion` prompt so the user sees exactly what they approve. Frame each question around one of:
+After each authoring step, review **only what just changed** — never re-review the whole file. Pick the single most relevant snippet (one concept, one functional spec, the module frontmatter, one requirement, one test plain file, one script change, one `config.yaml` entry) and embed it directly in the `AskUserQuestion` prompt so the user sees exactly what they approve. Frame each question around one of:
 
 - **Missing parts** — something that should be in the snippet but isn't (an attribute, a validation rule, an edge case, a missing concept).
 - **Possible extensions** — behavior or detail that could reasonably be expanded.
@@ -84,7 +84,7 @@ When entering a phase, read its reference file and walk its topics **in order**
 | 0 — What is the intent? | `references/phase-0-intent.md` | a concise intent brief covering the problem, primary user and outcome, and initial boundary is explicitly confirmed; nothing is written to disk |
 | 1 — What are we building? | `references/phase-1-product.md` | the new `***definitions***` and `***functional specs***`, plus any technology-free `***implementation reqs***`, are on disk and approved |
 | 2 — What tech should it use? | `references/phase-2-tech.md` | the new `***implementation reqs***` are on disk and approved |
-| 3 — How is testing done? | `references/phase-3-testing.md` | the `***test reqs***` (and `***acceptance tests***` if conformance is on) are on disk, the `test_scripts/` and `config.yaml`(s) exist, and `check-plain-env` passed or each gap was acknowledged |
+| 3 — How is testing done? | `references/phase-3-testing.md` | the `***test reqs***` (and the test plain files if conformance is on) are on disk, the `test_scripts/` and `config.yaml`(s) exist, and `check-plain-env` passed or each gap was acknowledged |
 | 4 — Validate and hand off | `references/phase-4-validate-handoff.md` | `plain-healthcheck` returned `PASS`, and the user has the render target plus every side-channel command |
 
 Between phases, summarize and get explicit overall confirmation before continuing — the intent brief