@turri-dev/cli 0.1.27 → 0.1.28-next.d5f2680

package/genome/skills/refactor-module/SKILL.md

@@ -2,9 +2,9 @@
 name: refactor-module
 description: >-
   Split a large ***plain module into smaller modules grouped by logical domain.
-  The resulting modules are connected via a requires chain so that functionality
+  The resulting modules are connected via a requires chain so that their behaviour
   is 100% preserved. Use when a module has become too large and its functional
-  specs span multiple distinct concerns that would be clearer as separate modules.
+  functional specs span multiple distinct concerns that would be clearer as separate modules.
 allowed-tools: [read, write, edit, bash, ls, grep, find]
 ---
 
@@ -19,9 +19,9 @@ allowed-tools: [read, write, edit, bash, ls, grep, find]
 
 ## Guiding Principle
 
-The refactoring is purely structural. The **combined behavior** of the resulting modules must be **identical** to the original module. No functional spec is added, removed, or weakened. The split is semantic — grouping related specs together — not behavioral.
+The refactoring is purely structural. The **combined behavior** of the resulting modules must be **identical** to the original module. No functional spec is added, removed, or weakened. The split is semantic — grouping related functional specs together — not behavioral.
 
-The spec is structural; the code is not. Once modules are split and specs move between them, the code already built no longer matches the module layout: specs move into modules the code was never built on, and no change to that code brings them in. **After a refactor, the whole requires chain is regenerated from scratch** — the existing code and conformance tests are taken out (their lineage keeps them) and every module is built again from the base of the chain upward. Say so up front: it is part of what the user agrees to (Phase 2e), and it is the last step of the skill (Phase 5).
+The ***plain is structural; the code is not. Once modules are split and functional specs move between them, the code already built no longer matches the module layout: functional specs move into modules the code was never built on, and no change to that code brings them in. **After a refactor, the whole requires chain is regenerated from scratch** — the existing code and conformance tests are taken out (their lineage keeps them) and every module is built again from the base of the chain upward. Say so up front: it is part of what the user agrees to (Phase 2e), and it is the last step of the skill (Phase 5).
 
 ## Input
 
@@ -30,7 +30,7 @@ The `.plain` file to refactor, plus guidance from the user on the desired groupi
 ## Phase 1 — Analyze the Current Module
 
 1. **Read the entire `.plain` file** — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read any `import` and `requires` chains to understand the full context.
-2. **Inventory the functional specs.** Number each spec and note which `:Concepts:` it references. Build a dependency map: which specs depend on earlier specs (by referencing behavior or state they introduced)?
+2. **Inventory the functional specs.** List each functional spec by its func-id and note which `:Concepts:` it references. Build a dependency map: which functional specs depend on earlier functional specs (by referencing behavior or state they introduced)?
 3. **Inventory the definitions.** For each concept, note which functional specs reference it. Identify concepts that are used across multiple logical groups vs. concepts used only within one group.
 4. **Identify logical groups.** Look for natural seams — clusters of functional specs that share concepts, represent a cohesive domain, or describe a single feature area. Common groupings:
    - Data model setup and CRUD operations
@@ -38,7 +38,7 @@ The `.plain` file to refactor, plus guidance from the user on the desired groupi
    - UI screens and navigation
    - Integrations and external interfaces
    - Statistics, reporting, and analytics
-5. **Verify group independence.** Each group's specs should form a contiguous or near-contiguous block in chronological order. If a group's specs are scattered and interleaved with other groups, the split boundary may need adjustment.
+5. **Verify group independence.** Each group's functional specs should form a contiguous or near-contiguous block in chronological order. If a group's functional specs are scattered and interleaved with other groups, the split boundary may need adjustment.
 
 ## Phase 2 — Plan the Split
 
@@ -46,7 +46,7 @@ Present the proposed split to the user and get explicit confirmation before maki
 
 ### 2a. Define the module chain
 
-The modules form a `requires` chain that preserves the original chronological ordering of functional specs. The first module in the chain contains the earliest specs; each subsequent module `requires` the previous one and adds the next logical group.
+The modules form a `requires` chain that preserves the original chronological ordering of functional specs. The first module in the chain contains the earliest functional specs; each subsequent module `requires` the previous one and adds the next logical group.
 
 ```
 original-module
@@ -61,9 +61,9 @@ If the original module already had `requires` or `import` dependencies, the firs
 ### 2b. Assign functional specs to modules
 
 Place each functional spec in exactly one module. The placement must respect chronological ordering:
-- Within each module, the specs appear in the same relative order as in the original.
-- Across the chain, the ordering is preserved: all specs in module A come before all specs in module B, which come before all specs in module C.
-- A spec **cannot** move to an earlier module than a spec it depends on.
+- Within each module, the functional specs appear in the same relative order as in the original.
+- Across the chain, the ordering is preserved: all functional specs in module A come before all functional specs in module B, which come before all functional specs in module C.
+- A functional spec **cannot** move to an earlier module than a functional spec it depends on.
 
 ### 2c. Assign definitions to modules
 
@@ -71,7 +71,7 @@ For each concept, determine where it belongs:
 
 | Concept usage | Placement |
 |---------------|-----------|
-| Used only within one module's specs | Define in that module |
+| Used only within one module's functional specs | Define in that module |
 | Used across multiple modules in the chain | Define in the first module that uses it, and add to that module's `exported_concepts` |
 | Already defined in an import template | Leave in the import — no change needed |
 
@@ -87,11 +87,11 @@ If many concepts are shared across all modules, consider creating a new import m
 
 Summarize for the user:
 - Number of resulting modules and their names
-- Which functional specs go in each module (listed by number or short description)
+- Which functional specs go in each module (listed by func-id)
 - The `requires` chain order
 - Any new import module being created
 - Which concepts are exported from each module
-- Confirmation that all original specs are accounted for (none lost)
+- Confirmation that all original functional specs are accounted for (none lost)
 - That the whole chain will be **regenerated from scratch** once the split is done: the code and conformance tests built so far are taken out (kept in the lineage) and everything is built again from the base module up — this takes as long and costs as much as building the original module did
 
 Get explicit user confirmation before proceeding — of the split and of regenerating from scratch.
@@ -108,10 +108,10 @@ If shared definitions or reqs are being moved to a new import template, create i
 
 Create the first module in the chain:
 1. Set the YAML frontmatter — inherit the original module's `import` references. Add `exported_concepts` for any concepts that downstream modules need.
-2. Add the `***definitions***` section with concepts used by this module's specs and concepts that need to be exported.
+2. Add the `***definitions***` section with concepts used by this module's functional specs and concepts that need to be exported.
 3. Add `***implementation reqs***` and `***test reqs***` specific to this module (if not fully covered by the import template).
 4. Add the `***functional specs***` assigned to this module, preserving their original order and exact wording.
-5. Carry over any `***acceptance tests***` nested under the moved functional specs.
+5. Move the test plain files of the moved functional specs into this module's folder, `tests/<module>/`, with `module:` set to the new module's name; func-ids and scenario text stay as they are.
 
 ### 3c. Create subsequent modules
 
@@ -121,12 +121,12 @@ For each subsequent module in the chain:
 3. Add `***definitions***` for concepts local to this module. Do **not** redefine concepts already available via `requires` (exported) or `import`.
 4. Add `***implementation reqs***` and `***test reqs***` specific to this module.
 5. Add the `***functional specs***` assigned to this module, preserving their original order and exact wording.
-6. Carry over any `***acceptance tests***`.
+6. Move the test plain files of the moved functional specs the same way.
 
 ### 3d. Handle the original module file
 
 After all new modules are created:
-- If the original module is being fully replaced (all specs moved out), delete it or rename it to avoid confusion.
+- If the original module is being fully replaced (all functional specs moved out), delete it or rename it to avoid confusion.
 - If the original module was required by other modules, update those modules to `require` the last module in the new chain instead — its accumulated code and previous functional specs cover the whole chain. Exported concepts are **not** transitive, though: if a downstream module references a concept now exported by an earlier module in the new chain, it must list that earlier module in its `requires` as well.
 
 ## Phase 4 — Verify
@@ -136,18 +136,18 @@ After all new modules are created:
 This is the most critical verification. Walk through every functional spec from the original module and confirm it appears in exactly one of the new modules. Nothing may be lost, weakened, modified, or left implicit.
 
 Checklist:
-- [ ] Total spec count across all new modules equals the original spec count
-- [ ] Each spec's text is identical to the original (no rewording)
-- [ ] Each spec's acceptance tests (if any) are carried over intact
+- [ ] The functional specs across all new modules are as many as the original's
+- [ ] Each functional spec's text is identical to the original (no rewording) and keeps its func-id
+- [ ] Each functional spec's test plain file moved with it, with `module:` updated and scenarios intact
 
 ### 4b. Chronological ordering check
 
-Verify that the chronological order of all functional specs — when read across the requires chain from base to leaf — matches the original ordering exactly. A spec must not appear before a spec it depends on.
+Verify that the chronological order of all functional specs — when read across the requires chain from base to leaf — matches the original ordering exactly. A functional spec must not appear before a functional spec it depends on.
 
 ### 4c. Concept availability check
 
 For each module, verify:
-- [ ] Every `:Concept:` referenced in its specs is either defined locally, available via `import`, or available via `exported_concepts` from a module listed in `requires`
+- [ ] Every `:Concept:` referenced in its functional specs is either defined locally, available via `import`, or available via `exported_concepts` from a module listed in `requires`
 - [ ] `exported_concepts` includes every concept that downstream modules need
 - [ ] No concept name collisions between modules
 
@@ -158,18 +158,18 @@ For each new module:
 - [ ] YAML frontmatter is correctly formatted
 - [ ] `requires` and `import` paths are correct
 - [ ] Module file is at the repository root (not in `template/`)
-- [ ] Specs are language-agnostic
+- [ ] Functional specs are language-agnostic
 - [ ] All external interfaces remain explicit
 
 ### 4e. Read all new modules
 
 Read each new `.plain` file in full and present the final structure to the user for approval. If the user requests changes, apply them and re-verify.
 
-Validate each new module with `turri validate <module>.plain` (or the `validate` tool) before going on: a module that does not parse cannot be regenerated.
+Parse each new module with `turri parse <module>.plain` (or the `parse` tool) before going on: a module that does not parse cannot be regenerated.
 
 ## Phase 5 — Regenerate the Chain from Scratch
 
-The split moves specs between modules, so the code built from the original module cannot be patched into the new layout: the chain is regenerated from scratch. Do not try to keep or reuse the existing code, and do not regenerate only what looks changed — modules have moved, and a codebase built without a module it now requires has to be started over anyway.
+The split moves functional specs between modules, so the code built from the original module cannot be patched into the new layout: the chain is regenerated from scratch. Do not try to keep or reuse the existing code, and do not regenerate only what looks changed — modules have moved, and a codebase built without a module it now requires has to be started over anyway.
 
 1. **Remind the user** what regenerating from scratch does — the code and conformance tests built so far are taken out, committed so the lineage keeps them, and the whole chain is built again from the base up — and that they already agreed to it in Phase 2e. Proceed only on that agreement.
 2. **Regenerate the tip of the chain from scratch, with its whole chain** — the last module, the one everything else is required by. From scratch for the tip alone is not enough: the modules below keep their code, and the tip starts from a copy of it, laid out for the old modules. With the whole chain, every module's code is taken out, the base's included, and the chain is built again from the bottom:
@@ -181,19 +181,19 @@ The split moves specs between modules, so the code built from the original modul
 ## Common Pitfalls
 
 ### Splitting too aggressively
-Creating many tiny modules with 1–2 specs each adds overhead without clarity. Aim for modules with 3–10 functional specs each, grouped around a cohesive theme.
+Creating many tiny modules with 1–2 functional specs each adds overhead without clarity. Aim for modules with 3–10 functional specs each, grouped around a cohesive theme.
 
 ### Breaking chronological order
-Specs that set up foundational behavior (entry point, database init, core CRUD) must stay in the base module even if they touch concepts from multiple domains. Only split when specs are cleanly separable.
+Functional specs that set up foundational behavior (entry point, database init, core CRUD) must stay in the base module even if they touch concepts from multiple domains. Only split when functional specs are cleanly separable.
 
 ### Forgetting exported_concepts
-If a concept defined in module A is referenced by a spec in module B (which requires A), the concept must be in A's `exported_concepts`. Missing exports cause rendering failures.
+If a concept defined in module A is referenced by a functional spec in module B (which requires A), the concept must be in A's `exported_concepts`. Missing exports cause regeneration failures.
 
-### Modifying spec text during the split
-This is a refactoring, not a rewrite. Spec text must be copied verbatim. If a spec needs rewording to work in its new module context, that is a sign the split boundary is wrong — adjust the grouping instead.
+### Modifying the ***plain during the split
+This is a refactoring, not a rewrite. Functional specs must be copied verbatim. If one needs rewording to work in its new module context, that is a sign the split boundary is wrong — adjust the grouping instead.
 
-### Losing acceptance tests
-Acceptance tests are nested under their parent functional spec. When moving a spec to a new module, its acceptance tests must move with it.
+### Losing test plain files
+A test plain file binds to its functional spec by `module:` and `func_id:`, and lives in its module's folder. When a functional spec moves to a new module, its test plain file moves to `tests/<new module>/` with `module:` changed; otherwise `turri parse` reports a file bound to no functional spec, and a functional spec with no test plain file.
 
 ### Regenerating only what changed
 After a split the existing code was built for a module layout that no longer exists. Regenerating incrementally either stops at a codebase that has to be started over or builds on code laid out for the old modules. Regenerate the whole chain from scratch.
@@ -202,8 +202,8 @@ After a split the existing code was built for a module layout that no longer exi
 
 - [ ] User confirmed the split plan before execution, including regenerating the whole chain from scratch
 - [ ] All original functional specs are present in exactly one new module — none lost
-- [ ] Spec text is identical to the original — no rewording
-- [ ] Acceptance tests moved with their parent specs
+- [ ] Every functional spec's text is identical to the original — no rewording
+- [ ] Test plain files moved with their functional specs and bound to the new module
 - [ ] Chronological order preserved across the requires chain
 - [ ] Every referenced `:Concept:` is available in each module (local, import, or exported)
 - [ ] `exported_concepts` are correctly set on each module
@@ -213,6 +213,6 @@ After a split the existing code was built for a module layout that no longer exi
 - [ ] Original module removed or updated
 - [ ] Downstream modules (if any) updated to require the chain tip, plus any earlier chain modules whose exported concepts they reference
 - [ ] User approved the final result
-- [ ] Every new module validates
+- [ ] Every new module parses
 - [ ] The tip of the chain regenerated from scratch with its whole chain, then any module that requires it
 - [ ] User told about the original module's leftover codebase, if there is one

package/genome/skills/resolve-section-ownership/SKILL.md

@@ -1,26 +1,26 @@
 ---
 name: resolve-section-ownership
 description: >-
-  Route every fact in a .plain bullet, section, or file to the section that owns it — splitting a bullet that carries several kinds of fact, and moving a misplaced one to where the renderer will read it. Use when a bullet answers more than one of what it is / what it does / how it is built / how it is tested, when a requirement looks like it is in the wrong section, or when auditing a file for section ownership. Not for a spec that is merely too large (use break-down-func-spec) or for two specs that contradict each other (use resolve-spec-conflict).
+  Route every fact in a .plain bullet, section, or file to the section that owns it — splitting a bullet that carries several kinds of fact, and moving a misplaced one to where turri will read it. Use when a bullet answers more than one of what it is / what it does / how it is built / how it is tested, when a requirement looks like it is in the wrong section, or when auditing a file for section ownership. Not for a functional spec that is merely too large (use break-down-func-spec) or for two that contradict each other (use resolve-spec-conflict).
 allowed-tools: [read, write, edit, ls, grep, find]
 ---
 
 # Resolve Section Ownership
 
-This is the ownership counterpart to `break-down-func-spec`. That skill splits one functional spec into several because it is **too large**; this one moves facts between sections because they are in the **wrong place**. The two are unrelated: a correctly placed spec can be too large, and a one-line bullet can be misplaced.
+This is the ownership counterpart to `break-down-func-spec`. That skill splits one functional spec into several because it is **too large**; this one moves facts between sections because they are in the **wrong place**. The two are unrelated: a correctly placed functional spec can be too large, and a one-line bullet can be misplaced.
 
 ## When to Use
 
 - A bullet answers more than one of *what is it*, *what does it do*, *how is it built*, *how is it tested*.
 - A requirement states a mechanism (retry, cache, token refresh, connection handling) but sits in `***functional specs***`.
-- A `:UnitTests:` fact sits in `***test reqs***`, or a `:ConformanceTests:` fact sits in `***implementation reqs***` — the generators read only their own section, so the fact is silently ignored today.
+- A `:UnitTests:` fact sits in `***test reqs***`, or a `:ConformanceTests:` fact sits in `***implementation reqs***` — the coding agent and the conformance agent each read only their own section, so the fact is silently ignored today.
 - A functional spec describes an external system rather than the software being built.
 - A whole file is being audited for placement.
 
 ## When Not to Use
 
-- The spec is correctly placed but too large → `break-down-func-spec`.
-- Two specs contradict each other → `analyze-func-specs`, then `resolve-spec-conflict`.
+- The functional spec is correctly placed but too large → `break-down-func-spec`.
+- Two functional specs contradict each other → `analyze-func-specs`, then `resolve-spec-conflict`.
 - The wording is merely verbose → trim per `concise-specs.md`; no fact changes section.
 
 ## Input
@@ -35,19 +35,19 @@ The bullet, section, or `.plain` file to resolve.
 4. **Route each fact** by the *Section ownership* table in `module-structure.md`. Where a fact resists the table, apply the question it encodes: **would a caller of the finished software observe this?** Yes → `***functional specs***`. No, it is how the result is reached → `***implementation reqs***`. It says what a term means → `***definitions***`. It shapes `:ConformanceTests:` → `***test reqs***`.
 5. **Split a fact that carries both a mechanism and its consequence.** The consequence is observable and becomes the functional spec; the mechanism becomes the implementation req. *"Sends the same idempotency key on every retry, so a retried write creates at most one record"* is two facts, not one.
 6. **Give each moved fact a subject that exists in the built system.** A fact leaving a functional spec often loses its subject: name the component that owns the behavior, and add it to `***definitions***` if it is not defined yet. `:Implementation:` is the whole codebase — use it only for a fact that holds everywhere.
-7. **Write each fact into its owning section** by that section's rule — `definitions.md`, `impl-reqs.md`, `test-reqs.md`, the acceptance tests in `func-specs.md`. A fact moving *into* `***functional specs***` goes through `func-specs.md` (*Adding a functional spec*): its complexity and conflict checks run before it is written in.
+7. **Write each fact into its owning section** by that section's rule — `definitions.md`, `impl-reqs.md`, `test-reqs.md`, and for a test scenario its functional spec's test plain file, by *Writing scenarios* in `test-plain-files.md`. A fact moving *into* `***functional specs***` goes through `func-specs.md` (*Adding a functional spec*): its complexity and conflict checks run before it is written in.
 8. **Remove each fact from where it no longer belongs.** If a bullet is left stating nothing observable, delete the bullet; do not leave a stub. Deleting the last bullet of a section deletes the section.
 9. **Verify nothing was lost and nothing was duplicated.** Walk every fact from the original text and confirm it appears in exactly one section. A fact that now reads as obvious in its new home is still a cut decision — make it deliberately, per `concise-specs.md`.
-10. **Run `validate`** on the module. Moving facts changes the renderable surface; do not finish while it reports errors.
+10. **Run `parse`** on the module. Moving facts changes what is regenerated; do not finish while it reports errors.
 11. **Read the file again** to confirm canonical section order (`***definitions***` → `***implementation reqs***` → `***test reqs***` → `***functional specs***`), correct syntax, and that every referenced concept is still defined before use.
 
 ## Error Handling
 
-- **The complexity check finds the moved fact too complex** → the fact was a whole spec in disguise; run `break-down-func-spec` on it, then place the resulting specs.
+- **The complexity check finds the moved fact too complex** → the fact was a whole functional spec in disguise; run `break-down-func-spec` on it, then place the resulting functional specs.
 - **The conflict check reports a conflict** → resolve it with `resolve-spec-conflict` **before** removing the fact from its old section, so no version of it is lost in between.
 - **A fact appears to belong to two sections** → it is two facts; split it per step 5. If it still resists, it is a mechanism whose consequence has not been written down — write the consequence, and the split follows.
 - **The owning section does not exist in the file** → create it in canonical order. An import module carries no `***functional specs***` at all (see `import-modules.md`), so an observable fact found there belongs on the root module that imports it.
-- **The move empties a functional spec** → delete the spec rather than leaving a placeholder, and check whether any acceptance test nested under it must move or go with it.
+- **The move empties a functional spec** → delete the functional spec rather than leaving a placeholder, and delete its test plain file with it, moving any scenario that still fits to the functional spec it now tests (*Keeping test plain files in step* in `test-plain-files.md`).
 
 ## Worked examples
 

package/genome/skills/resolve-spec-conflict/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: resolve-spec-conflict
 description: >-
-  Resolve a conflict between two functional specs in a ***plain spec file. Use
-  when conformance tests for a previously passing spec start failing after a new
-  spec is rendered, or when a potential conflict is detected while adding a new
+  Resolve a conflict between two functional specs in a .plain file. Use
+  when conformance tests for a previously passing functional spec start failing after a new
+  one is regenerated, or when a potential conflict is detected while adding a new
   functional spec (the conflict check of `func-specs.md`).
 allowed-tools: [read, write, edit, ls, grep, find]
 ---
@@ -13,15 +13,15 @@ allowed-tools: [read, write, edit, ls, grep, find]
 ## When This Applies
 
 A conflict exists (or is suspected) when:
-- Conformance tests for a **previously passing** functional spec begin to fail after a new spec is rendered.
-- A new spec being added appears to contradict an existing spec.
-- Two specs make incompatible assertions about the same behavior, data, or state.
+- Conformance tests for a **previously passing** functional spec begin to fail after a new one is regenerated.
+- A new functional spec being added appears to contradict an existing functional spec.
+- Two functional specs make incompatible assertions about the same behavior, data, or state.
 
 ## Workflow
 
 ### Step 1: Identify the Conflicting Pair
 
-Read the `.plain` file and pinpoint the two specs in tension. If the conflict was detected via a conformance test failure, also read the failing test and the generated implementation in `plain_modules/` to understand what behavior changed.
+Read the `.plain` file and pinpoint the two functional specs in tension. If the conflict was detected via a conformance test failure, also read the failing test and the generated implementation in `plain_modules/` to understand what behavior changed.
 
 ### Step 2: Diagnose the Root Cause
 
@@ -29,68 +29,74 @@ There are three possible outcomes — determine which one applies **before** mak
 
 | Outcome | Symptom | Fix |
 |---------|---------|-----|
-| **Implementation is incorrect** | Generated code doesn't match the spec's intent. The specs themselves are fine. | Clarify the ambiguous spec so the renderer interprets it correctly. Re-render. |
-| **Conformance tests are incorrect** | The tests don't accurately verify the spec. The implementation is actually correct. | Adjust `***test reqs***` or `***acceptance tests***` to guide better test generation. Re-render. |
-| **Requirements truly conflict** | The two specs are inherently contradictory — no implementation can satisfy both. | One or both specs must be revised. See Step 3. |
+| **Implementation is incorrect** | Generated code doesn't match the functional spec's intent. The functional specs themselves are fine. | Clarify the ambiguous functional spec so the coding agent interprets it correctly. Regenerate. |
+| **Conformance tests are incorrect** | The tests don't accurately verify the functional spec. The implementation is actually correct. | Adjust `***test reqs***`, or a scenario in the test plain file (*Writing scenarios* in `test-plain-files.md`), to guide better test generation. Regenerate. |
+| **Requirements truly conflict** | The two functional specs are inherently contradictory — no implementation can satisfy both. | One or both functional specs must be revised. See Step 3. |
 
 **How to diagnose:**
 1. Read both functional specs carefully. Can a single implementation satisfy both simultaneously?
-2. If yes → the specs are compatible; the issue is ambiguity (outcome 1) or bad tests (outcome 2).
+2. If yes → the functional specs are compatible; the issue is ambiguity (outcome 1) or bad tests (outcome 2).
 3. If no → the requirements truly conflict (outcome 3).
 
 ### Step 3: Resolve the Conflict
 
 When the requirements truly conflict, choose a resolution strategy:
 
-**Strategy A: Add detail to disambiguate.** Often the specs aren't contradictory — they're just ambiguous enough that the renderer picks a conflicting interpretation. Adding explicit context to one or both specs eliminates the ambiguity.
+**Strategy A: Add detail to disambiguate.** Often the functional specs aren't contradictory — they're just ambiguous enough that the coding agent picks a conflicting interpretation. Adding explicit context to one or both functional specs eliminates the ambiguity.
 
 Before (ambiguous):
 ```plain
 ***functional specs***
 
-- All :Resource: items are returned.
+# list-resources
+All :Resource: items are returned.
 
-- Only active :Resource: items are returned.
+# list-active-resources
+Only active :Resource: items are returned.
 ```
 
 After (disambiguated):
 ```plain
 ***functional specs***
 
-- All :Resource: items are returned when no filter is specified.
+# list-resources
+All :Resource: items are returned when no filter is specified.
 
-- When the "active" filter is specified, only active :Resource: items are returned.
+# list-active-resources
+When the "active" filter is specified, only active :Resource: items are returned.
 ```
 
-**Strategy B: Revise the newer spec.** If the new spec introduced the conflict, rewrite it to be compatible with the established behavior from earlier specs.
+**Strategy B: Revise the newer functional spec.** If the new functional spec introduced the conflict, rewrite it to be compatible with the established behavior from earlier functional specs.
 
-**Strategy C: Revise the older spec.** If the older spec was under-specified and the new requirement reveals a better design, update the older spec. This is more disruptive — all conformance tests for that spec and everything after it may need re-rendering.
+**Strategy C: Revise the older functional spec.** If the older functional spec was under-specified and the new requirement reveals a better design, update the older functional spec. This is more disruptive — the older one's code is patched in place, and the functional specs that rely on what it did may need changing too.
 
-**Strategy D: Merge into one spec.** If the two specs describe overlapping behavior, combine them into a single, clear spec. Remove the redundant one. Be mindful of the 200 LOC limit.
+**Strategy D: Merge into one.** If the two functional specs describe overlapping behavior, combine them into a single, clear one. Remove the redundant one and its test plain file, moving any scenario that still fits into the kept functional spec's file. Be mindful of the 200 LOC limit.
 
 ### Step 4: Validate the Resolution
 
 After editing:
 1. Re-read the full `***functional specs***` section to confirm no new conflicts were introduced.
-2. Check that any revised spec still respects the 200 LOC limit.
-3. Check that chronological ordering still makes sense (earlier specs should not depend on later ones).
-4. If resolving via test adjustments, verify the `***test reqs***` or `***acceptance tests***` changes are appropriate.
+2. Check that any revised functional spec still respects the 200 LOC limit.
+3. Check that chronological ordering still makes sense (earlier functional specs should not depend on later ones).
+4. If resolving via test adjustments, verify the `***test reqs***` or test plain file changes are appropriate.
+5. Bring the test plain file of every revised functional spec in step with its new text, in the same ***plain diff (*Keeping test plain files in step* in `test-plain-files.md`).
 
 ## Prevention (while adding a functional spec)
 
-Before adding a new spec, run through this quick conflict check:
+Before adding a new functional spec, run through this quick conflict check:
 
-1. List every existing functional spec that touches the same `:Concepts:` as the new spec.
-2. For each, ask: "Can a single implementation satisfy both this existing spec and the new one?"
-3. If any answer is "not obviously yes" — add explicit detail to the new spec to eliminate the ambiguity **before** inserting it.
+1. List every existing functional spec that touches the same `:Concepts:` as the new functional spec.
+2. For each, ask: "Can a single implementation satisfy both this existing functional spec and the new one?"
+3. If any answer is "not obviously yes" — add explicit detail to the new functional spec to eliminate the ambiguity **before** inserting it.
 
 ## Validation Checklist
 
 - [ ] Root cause diagnosed (implementation / tests / true conflict)
 - [ ] Resolution strategy chosen and applied
-- [ ] Revised specs are language-agnostic
-- [ ] Revised specs trimmed per `concise-specs.md` — added disambiguation stays as short as it can be
-- [ ] Revised specs each imply ≤ 200 LOC
+- [ ] Revised functional specs are language-agnostic
+- [ ] Revised functional specs trimmed per `concise-specs.md` — added disambiguation stays as short as it can be
+- [ ] Revised functional specs each imply ≤ 200 LOC
 - [ ] No new conflicts introduced by the fix
 - [ ] Chronological ordering preserved
 - [ ] All referenced `:Concepts:` are still defined
+- [ ] Test plain files of the revised functional specs in step with them (`test-plain-files.md`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.27",
+  "version": "0.1.28-next.d5f2680",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -33,20 +33,21 @@
     "mutation": "node scripts/mutation.mjs",
     "conform": "tsx src/conform-cli.ts",
     "regenerate": "tsx src/regenerate-cli.ts",
-    "validate": "tsx src/validate-cli.ts",
+    "parse": "tsx src/parse-cli.ts",
     "doctor": "node bin/turri.mjs doctor",
     "build": "node scripts/build.mjs",
-    "prepack": "npm run build",
-    "grammar:sync": "node scripts/sync-plyn-grammar.mjs"
+    "prepack": "npm run build"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "^1.2.0",
-    "@earendil-works/pi-tui": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@langchain/langgraph": "1.4.15",
     "gray-matter": "^4.0.3",
     "js-yaml": "^5.4.2",
     "liquidjs": "^10.29.0",
     "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm-table": "^2.0.0",
+    "micromark-extension-gfm-table": "^2.1.1",
     "remark-parse": "^11.0.0",
     "typebox": "^1.3.7",
     "unified": "^11.0.5"

package/dist/regenerate/choose-conformance.d.ts

@@ -1,32 +0,0 @@
-import type { TouchedSpec } from "./drift.ts";
-/**
- * Which functional specs get conformance tests, under `conformance-tests: chosen` or `module`, is this agent's to choose -
- * in the chat and on the command line alike, on the chooser's model. Under chosen it is asked as each code pulse ends,
- * of what that pulse regenerated; under module once, when the whole module is regenerated, and it plans the conformance
- * pulses too. It reads the module's spec and names the ones worth black-box tests, and why. Being asked inside the pulse,
- * the choice is made before anything can be built on the module: nothing has to be stopped for it.
- */
-export interface ConformanceChoice {
-    frids: string[];
-    why: string;
-    /** Under module: the conformance pulses, each the functional specs it tests together. */
-    groups?: string[][];
-}
-/** What the chooser is asked: the module's spec, and the functional specs to choose from. */
-export declare function choicePrompt(plainFile: string, specs: TouchedSpec[], spec: string, budget?: number, when?: "pulse" | "module"): string;
-/** Ask the chooser, on `model`. Nothing chosen when it does not answer, or answers with numbers not offered. */
-export declare function chooseConformance(options: {
-    plainFile: string;
-    specs: TouchedSpec[];
-    model?: string;
-    budget?: number;
-    when?: "pulse" | "module";
-}): Promise<ConformanceChoice>;
-/**
- * The work loop's chooser, the chat's and the command line's alike: asked as a pulse ends, it asks chooseConformance on
- * the harness model. A functional spec passed over is not offered again for the same text - only once it changes.
- */
-export declare function conformanceChooser(options: {
-    model: () => string | undefined;
-    dryRun?: boolean;
-}): (plainFile: string, specs: TouchedSpec[], budget: number | undefined, when: "pulse" | "module") => Promise<ConformanceChoice | undefined>;

package/dist/regenerate/choose-conformance.js

@@ -1,117 +0,0 @@
-import { readFileSync } from "node:fs";
-import { basename, dirname } from "node:path";
-import { defineTool } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { ask, BEGIN, createExecutor } from "../pi.js";
-import { reportActivity } from "./activity.js";
-/** What the chooser is asked: the module's spec, and the functional specs to choose from. */
-export function choicePrompt(plainFile, specs, spec, budget, when = "pulse") {
-    return [
-        `You choose which functional specs of the ***plain module \`${basename(plainFile)}\` get black-box conformance tests.`,
-        when === "module"
-            ? "conformance-tests: module - the whole module is regenerated now, and these of its functional specs are built and no conformance test is for them or scheduled:"
-            : "conformance-tests: chosen - a code pulse has just regenerated these, and no conformance test is for them or scheduled:",
-        ...specs.map((touched) => `- fs ${touched.frid}: ${touched.text}`),
-        "",
-        `Decide which of them black-box conformance tests are worth it for - what a user or a client of ${basename(plainFile)} relies on,`,
-        "not an internal detail its unit tests already cover - and say why. The rest stay without. A functional spec with",
-        "acceptance tests always has them: it is not among these. Choosing none is an answer too.",
-        ...(budget !== undefined
-            ? [`Choose at most ${budget} - the module's conformance budget: rank them by what a client of the module relies on most, and say why the ones you choose come before the rest.`]
-            : []),
-        ...(when === "module"
-            ? [
-                "",
-                "Plan them too: in groups, each a conformance pulse - the functional specs a client exercises together in one, those",
-                "that share nothing apart. Every one you choose is in one group.",
-            ]
-            : []),
-        "",
-        `Call choose_conformance once, with the numbers of those you choose${when === "module" ? ", the groups" : ""} and why.`,
-        "",
-        `<spec file="${basename(plainFile)}">`,
-        spec.trimEnd(),
-        "</spec>",
-    ].join("\n");
-}
-/** Ask the chooser, on `model`. Nothing chosen when it does not answer, or answers with numbers not offered. */
-export async function chooseConformance(options) {
-    const planning = options.when === "module";
-    let answer;
-    const offered = new Set(options.specs.map((touched) => touched.frid));
-    const tool = defineTool({
-        name: "choose_conformance",
-        label: "Choose the conformance tests",
-        description: "The functional specs, by number, that get black-box conformance tests - none, some or all of those offered - and why.",
-        parameters: Type.Object({
-            frids: Type.Array(Type.String({ description: 'A functional spec\'s number, as offered - e.g. "2" or "3.1"' })),
-            why: Type.String({ description: "Why these, and why not the rest" }),
-            ...(planning ? { groups: Type.Array(Type.Array(Type.String()), { description: "The conformance pulses: each the numbers of the functional specs it tests together - every one chosen in one" }) } : {}),
-        }),
-        async execute(_id, params) {
-            const { frids, why, groups } = params;
-            if (planning && groups !== undefined) {
-                const grouped = groups.flat();
-                const outside = grouped.filter((frid) => !frids.includes(frid));
-                const left = frids.filter((frid) => !grouped.includes(frid));
-                if (outside.length > 0 || left.length > 0 || new Set(grouped).size !== grouped.length) {
-                    return { content: [{ type: "text", text: `Not recorded: every one chosen is in exactly one group, and nothing else is${outside.length > 0 ? ` - fs ${outside.join(", ")} grouped, not chosen` : ""}${left.length > 0 ? ` - fs ${left.join(", ")} chosen, in no group` : ""}. Call it again.` }], details: {} };
-                }
-            }
-            const unknown = frids.filter((frid) => !offered.has(frid));
-            if (options.budget !== undefined && new Set(frids).size > options.budget) {
-                return { content: [{ type: "text", text: `Not recorded: the module's conformance budget allows ${options.budget}, and you chose ${new Set(frids).size}. Choose the ${options.budget} that matter most, and call it again.` }], details: {} };
-            }
-            if (unknown.length > 0) {
-                return { content: [{ type: "text", text: `Not offered: fs ${unknown.join(", ")}. Choose from ${[...offered].join(", ")}, and call it again.` }], details: {} };
-            }
-            answer = { frids: [...new Set(frids)], why, ...(planning && groups !== undefined && groups.length > 0 ? { groups: groups.filter((group) => group.length > 0) } : {}) };
-            return { content: [{ type: "text", text: "Recorded." }], details: {}, terminate: true };
-        },
-    });
-    const session = await createExecutor({
-        cwd: dirname(options.plainFile),
-        customTools: [tool],
-        tools: [tool.name],
-        model: options.model,
-        label: `${basename(options.plainFile, ".plain")} conformance chooser`,
-        role: "chooser",
-        task: choicePrompt(options.plainFile, options.specs, readFileSync(options.plainFile, "utf8"), options.budget, options.when),
-        budget: { calls: 3, finish: [tool.name] },
-    });
-    try {
-        await ask(session, BEGIN);
-        if (answer === undefined)
-            await ask(session, "You did not call choose_conformance. Call it now.");
-    }
-    finally {
-        session.dispose();
-    }
-    if (answer === undefined) {
-        reportActivity(`  the conformance chooser gave no answer for ${basename(options.plainFile)}: none chosen`);
-        return { frids: [], why: "the chooser gave no answer" };
-    }
-    return answer;
-}
-/**
- * The work loop's chooser, the chat's and the command line's alike: asked as a pulse ends, it asks chooseConformance on
- * the harness model. A functional spec passed over is not offered again for the same text - only once it changes.
- */
-export function conformanceChooser(options) {
-    const offered = new Set();
-    return async (plainFile, specs, budget, when) => {
-        const fresh = specs.filter((touched) => !offered.has(`${plainFile}\n${touched.frid}\n${touched.text}`));
-        if (fresh.length === 0 || options.dryRun === true)
-            return undefined;
-        for (const touched of fresh)
-            offered.add(`${plainFile}\n${touched.frid}\n${touched.text}`);
-        try {
-            const model = options.model();
-            return await chooseConformance({ plainFile, specs: fresh, when, ...(model !== undefined ? { model } : {}), ...(budget !== undefined ? { budget } : {}) });
-        }
-        catch (error) {
-            reportActivity(`  choosing the conformance tests of ${basename(plainFile)} failed: ${error instanceof Error ? error.message : String(error)}`);
-            return undefined;
-        }
-    };
-}