@turri-dev/cli 0.1.27 → 0.2.0

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

@@ -1,10 +1,10 @@
 ---
 name: analyze-func-specs
 description: >-
-  Analyze a batch of functional specs from a ***plain spec file to determine
+  Analyze a batch of functional specs from a .plain file to determine
   which pairs conflict. Replaces the pair-by-pair `analyze-2-func-specs` flow
-  when a caller wants to check many specs at once (e.g. a new spec against
-  every existing spec, or a freshly inserted batch against itself).
+  when a caller wants to check many functional specs at once (e.g. a new one against
+  every existing one, or a freshly inserted batch against itself).
 allowed-tools: [read, ls, grep, find]
 ---
 
@@ -15,18 +15,18 @@ allowed-tools: [read, ls, grep, find]
 A **set of two or more functional specs** to check against each other. Callers typically supply one of:
 
 - A whole `***functional specs***` section to self-check.
-- 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.
+- A new functional spec (or batch of them) **plus** the existing functional specs from the same file and any `requires` modules.
+- An explicit list of functional 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 functional 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.
 
 ## Workflow
 
-1. **Read all input specs and the relevant `***definitions***`** so every `:Concept:` is understood.
-2. **Establish chronological order** across the batch. Earlier specs are considered to have been rendered first; later specs are evaluated with the earlier ones in context. If the caller already provided an order, preserve it.
-3. **Generate the pair list.** Enumerate every unordered pair `(Sᵢ, Sⱼ)` with `i < j`. Skip pairs where the two specs share no `:Concept:` and no overlapping subject — they are trivially compatible and listing them adds noise.
+1. **Read all input functional specs and the relevant `***definitions***`** so every `:Concept:` is understood.
+2. **Establish chronological order** across the batch. Earlier functional specs are considered to have been regenerated first; later ones are evaluated with the earlier ones in context. If the caller already provided an order, preserve it.
+3. **Generate the pair list.** Enumerate every unordered pair of functional specs, the earlier first. Skip pairs where the two share no `:Concept:` and no overlapping subject — they are trivially compatible and listing them adds noise.
 4. **Run the conflict analysis below on each remaining pair.** Use the same checklist that the legacy `analyze-2-func-specs` skill used, but apply it pair by pair across the batch in a single pass — do not require the caller to invoke the analyzer once per pair.
 5. **Record every CONFLICTING pair.** Compatible pairs are not listed individually; only the conflicts are emitted.
 6. **Output the verdict** in the format below. No reasoning, no category labels, no resolution suggestions.
@@ -37,11 +37,14 @@ Work through each question for the pair under inspection. If any answer is "yes"
 
 ### 1. Direct Contradiction
 
-Do the two specs make mutually exclusive assertions about the same behavior?
+Do the two functional specs make mutually exclusive assertions about the same behavior?
 
 ```
-Spec A: :Resource: items are returned sorted by name in ascending order.
-Spec B: :Resource: items are returned sorted by creation date in descending order.
+# sort-by-name
+:Resource: items are returned sorted by name in ascending order.
+
+# sort-by-date
+:Resource: items are returned sorted by creation date in descending order.
 
 Verdict: CONFLICTING — both define the sort order for the same response,
 but specify different fields and directions. A single implementation cannot
@@ -50,34 +53,43 @@ satisfy both unless scoped to different contexts.
 
 ### 2. State or Data Conflict
 
-Does one spec set a state or value that the other spec assumes is different?
+Does one functional spec set a state or value that the other assumes is different?
 
 ```
-Spec A: :TaskList: is initially empty.
-Spec B: :TaskList: contains a default "Welcome" :Task: on first load.
+# empty-task-list
+:TaskList: is initially empty.
+
+# welcome-task
+:TaskList: contains a default "Welcome" :Task: on first load.
 
 Verdict: CONFLICTING — both define the initial state of :TaskList: differently.
 ```
 
 ### 3. Behavioral Override
 
-Does the later spec silently replace behavior established by the earlier spec without acknowledging it?
+Does the later functional spec silently replace behavior established by the earlier one without acknowledging it?
 
 ```
-Spec A: :User: credentials are validated using an API key.
-Spec B: :User: credentials are validated using OAuth 2.0.
+# api-key-auth
+:User: credentials are validated using an API key.
+
+# oauth-auth
+:User: credentials are validated using OAuth 2.0.
 
 Verdict: CONFLICTING — both define the authentication mechanism but pick
-different approaches. The later spec overrides the earlier one.
+different approaches. The later one overrides the earlier one.
 ```
 
 ### 4. Scope Ambiguity
 
-Are the two specs ambiguous enough that a renderer could interpret them as conflicting, even if the user intends them to be complementary?
+Are the two functional specs ambiguous enough that a coding agent could interpret them as conflicting, even if the user intends them to be complementary?
 
 ```
-Spec A: All :Resource: items are returned.
-Spec B: Only active :Resource: items are returned.
+# list-resources
+All :Resource: items are returned.
+
+# list-active-resources
+Only active :Resource: items are returned.
 
 Verdict: CONFLICTING (ambiguous) — "all" vs "only active" appear contradictory.
 Could be resolved by scoping each to different conditions (e.g., filtered vs unfiltered).
@@ -85,13 +97,16 @@ Could be resolved by scoping each to different conditions (e.g., filtered vs unf
 
 ### 5. Shared Concept, Different Constraints
 
-Do both specs impose constraints on the same `:Concept:` that cannot coexist?
+Do both functional specs impose constraints on the same `:Concept:` that cannot coexist?
 
 ```
-Spec A: :BatchSize: is 100 items.
-Spec B: :BatchSize: is 50 items for :Resource: types with attachments.
+# default-batch-size
+:BatchSize: is 100 items.
+
+# attachment-batch-size
+:BatchSize: is 50 items for :Resource: types with attachments.
 
-Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
+Verdict: COMPATIBLE — attachment-batch-size adds a conditional refinement, not a contradiction.
 ```
 
 ## Output Format
@@ -104,20 +119,19 @@ If **no pair** is conflicting:
 COMPATIBLE
 ```
 
-If **one or more pairs** are conflicting, emit `CONFLICTING` followed by one line per conflicting pair, in `Sᵢ x Sⱼ` form (using the identifiers from the input, with `i < j`), sorted lexicographically:
+If **one or more pairs** are conflicting, emit `CONFLICTING` followed by one line per conflicting pair, in `<a> x <b>` form (the identifiers from step 1, the one that comes first in the input on the left), sorted lexicographically:
 
 ```
 CONFLICTING
-S1 x S4
-S2 x S3
-S3 x S5
+add-task x import-tasks
+list-tasks x S2
 ```
 
 Rules for the output:
 
 - Do **not** list compatible pairs.
 - Do **not** include reasoning, checklist categories, or fixes — the caller decides what to do with each conflict (typically: invoke `resolve-spec-conflict` on each pair).
-- If the input contained fewer than two specs, emit `COMPATIBLE` (nothing to compare).
-- Identifiers must match exactly what the caller provided (or the `S1`, `S2`, … fallback assigned in step 1).
+- If the input contained fewer than two functional specs, emit `COMPATIBLE` (nothing to compare).
+- Identifiers must match exactly what *Input* settled: the func-ids, the caller's own labels, or the `S1`, `S2`, … fallback for a draft.
 
 The internal pairwise analysis informs the verdict but must not appear in the output.

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

@@ -1,19 +1,19 @@
 ---
 name: break-down-func-spec
 description: >-
-  Break down a functional spec that is too complex into smaller specs that
-  each imply ≤ 200 lines of code. Use when a spec is judged too large against
+  Break down a functional spec that is too complex into smaller ones that
+  each imply ≤ 200 lines of code. Use when a functional spec is judged too large against
   the complexity limit (`func-specs.md`), before or after it is written in.
 allowed-tools: [read, write, edit, ls, grep, find]
 ---
 
-# Break Down Functional Spec
+# Break Down Functional Functional spec
 
 ## When to Use
 
-- A spec is judged to exceed the 200 LOC limit (`func-specs.md`, *Complexity limit*) and needs to be split before it is written in.
-- A spec already written in turns out too large - its pulse could not get its unit tests to pass.
-- A spec bundles multiple behaviors, constructs, or concerns that should be separated.
+- A functional spec is judged to exceed the 200 LOC limit (`func-specs.md`, *Complexity limit*) and needs to be split before it is written in.
+- A functional spec already written in turns out too large - its pulse could not get its unit tests to pass.
+- A functional spec bundles multiple behaviors, constructs, or concerns that should be separated.
 
 ## Input
 
@@ -22,184 +22,208 @@ The functional spec to break down, plus the full `.plain` file it belongs to.
 ## Workflow
 
 1. **Read the full `.plain` file** — definitions, implementation reqs, and all functional specs (including `requires` modules) to understand context.
-2. **Identify the spec to break down** — the one flagged as too complex or pointed to by the user.
+2. **Identify the functional spec to break down** — the one flagged as too complex or pointed to by the user.
 3. **Analyze why it is too complex** — use the signs in `func-specs.md` (*Complexity limit*):
    - Multiple distinct behaviors bundled together?
    - Too many new constructs introduced at once?
    - Complex branching logic or conditional paths?
-   - Cross-cutting concerns mixed with core functionality?
-   - A full UI screen described in one spec?
+   - Cross-cutting concerns mixed with core behaviour?
+   - A full UI screen described in one functional spec?
    - Complex data transformations across multiple entities?
    - Implies one substantial technical component (engine, parser, scheduler, algorithm, state machine, sync mechanism) that must be built in code?
-4. **Identify the split boundaries** — find the natural seams where the spec can be divided. Each resulting spec must be:
-   - Independently meaningful (makes sense on its own with previous specs as context)
-   - Self-contained (does not require a later spec to be useful)
+4. **Identify the split boundaries** — find the natural seams where the functional spec can be divided. Each resulting one must be:
+   - Independently meaningful (makes sense on its own with the functional specs before it as context)
+   - Self-contained (does not require a later functional 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.
-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** — judge each against the complexity limit, and split again any that is still too large.
-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.
+5. **Draft the replacements** — write the smaller functional specs in chronological order, each with its own func-id per `semantic-ids.md`; the replacement that keeps the original's main behaviour may keep the original's func-id. The first replacement typically sets up the foundation, and subsequent ones layer behavior on top.
+6. **Verify functional completeness** — this is critical. The replacements taken together must cover **100% of the behaviour** the original describes. Walk through every behavior, condition, and detail in the original and confirm it appears in exactly one of the replacements. Nothing may be lost, weakened, or left implicit. If any behaviour from the original is missing, add it to the appropriate replacement or create an additional one.
+7. **Verify each replacement** — judge each against the complexity limit, and split again any that is still too large.
+8. **Check for conflicts** — run `analyze-func-specs` **once** with the full set of replacements plus every existing functional 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 functional spec (heading and body) and insert the replacements in its position, each as a `# <func-id>` heading with its body, preserving chronological order.
+10. **Bring the test plain files in step**, in the same ***plain diff - every replacement gets its test plain file, each scenario of the original's moves to the replacement it tests, and the original's file is deleted when its func-id is gone (*Keeping test plain files in step* in `test-plain-files.md`). No scenario is written for a replacement that the original's did not have.
+11. **Read the file again** to confirm correct placement and syntax.
 
 ## Splitting Strategies
 
 ### Strategy 1: Separate Distinct Behaviors
 
-If the spec bundles multiple independently testable actions, split each into its own spec.
+If the functional spec bundles multiple independently testable actions, split each into its own.
 
 **Before:**
 ```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
 
-If the spec introduces a new construct and immediately defines complex behavior on it, split into setup + behavior.
+If the functional spec introduces a new construct and immediately defines complex behavior on it, split into setup + behavior.
 
 **Before:**
 ```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
 
-If the spec mixes primary functionality with error handling, retries, caching, pagination, or logging, pull cross-cutting concerns into their own specs.
+If the functional spec mixes primary behaviour with error handling, retries, caching, pagination, or logging, pull cross-cutting concerns into their own functional specs.
 
 **Before:**
 ```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
 
-If the spec describes different modes or branches, give each its own spec.
+If the functional spec describes different modes or branches, give each its own.
 
 **Before:**
 ```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
 
-If the spec describes a full screen, split into layout + individual interactive elements.
+If the functional spec describes a full screen, split into layout + individual interactive elements.
 
 **Before:**
 ```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
 
-Sometimes a spec is too complex not because it bundles many behaviors, but because it implies building one substantial technical component inline — an engine, parser, scheduler, layout algorithm, state machine, or sync mechanism. Splitting the behavior sideways does not help when the weight sits in that single component. Instead, pull the component out: define a concept for it, build it in its own dedicated spec placed **earlier** in the chain, then rewrite the original to use the component **by reference**. Because specs render incrementally top-to-bottom, the original now implies far less code — it wires up a component that already exists rather than implementing it from scratch.
+Sometimes a functional spec is too complex not because it bundles many behaviors, but because it implies building one substantial technical component inline — an engine, parser, scheduler, layout algorithm, state machine, or sync mechanism. Splitting the behavior sideways does not help when the weight sits in that single component. Instead, pull the component out: define a concept for it, build it in its own dedicated functional spec placed **earlier** in the chain, then rewrite the original to use the component **by reference**. Because functional specs are regenerated incrementally top-to-bottom, the original now implies far less code — it wires up a component that already exists rather than implementing it from scratch.
 
-Define the component concept in `***definitions***` (per `definitions.md`) before the first spec that references it.
+Define the component concept in `***definitions***` (per `definitions.md`) before the first functional spec that references it.
 
 **Before:**
 ```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 - one that `requires` it, following `requires-modules.md`, or with `refactor-module` - instead of a sibling spec.
+The extracted component's functional spec and the rewritten original must together still cover 100% of the original behaviour (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 - one that `requires` it, following `requires-modules.md`, or with `refactor-module` - instead of a sibling functional spec.
 
 ## Preserving Chronological Order
 
-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.
+The replacements take the position of the original. Earlier functional specs remain unchanged. The first replacement should make sense given only the functional specs above it. Each subsequent replacement 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's test plain file is split the same way: each scenario moves to the replacement it tests, and one that no longer fits a single replacement is rewritten to fit the one it tests most. A replacement no scenario moves to gets no test plain file - never an empty one (see `test-plain-files.md`).
 
 ## Validation Checklist
 
-- [ ] Original spec has been removed from the file
-- [ ] Replacement specs together cover 100% of the original spec's functionality — nothing lost
-- [ ] Each replacement spec implies ≤ 200 LOC (judged against the complexity limit)
-- [ ] No conflicts between replacement specs and existing specs (verified via one batched `analyze-func-specs` call)
-- [ ] No conflicts between the replacement specs themselves (covered by the same batched call)
-- [ ] Replacement specs are in correct chronological order
-- [ ] Each replacement spec is independently meaningful
-- [ ] All `:Concepts:` referenced in replacement specs are defined
-- [ ] Any extracted technical component is defined as a concept, built by its own earlier spec, and only **referenced** (not re-described) by the original
-- [ ] Replacement specs are language-agnostic
-- [ ] Replacement specs trimmed per `concise-specs.md` — a split is not a licence to re-add prose
+- [ ] The original functional spec has been removed from the file
+- [ ] The replacements together cover 100% of the original's behaviour — nothing lost
+- [ ] Each replacement implies ≤ 200 LOC (judged against the complexity limit)
+- [ ] No conflicts between the replacements and existing functional specs (verified via one batched `analyze-func-specs` call)
+- [ ] No conflicts between the replacements themselves (covered by the same batched call)
+- [ ] The replacements are in correct chronological order
+- [ ] Each replacement is independently meaningful
+- [ ] All `:Concepts:` referenced in the replacements are defined
+- [ ] Any extracted technical component is defined as a concept, built by its own earlier functional spec, and only **referenced** (not re-described) by the original
+- [ ] The replacements are language-agnostic
+- [ ] The replacements 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, every original scenario moved or rewritten, none bound to a func-id that no longer exists

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

@@ -34,11 +34,11 @@ The set of modules to consolidate from, plus optionally the name for the new (or
    - Whether it is currently in an `exported_concepts` list
    - Which other concepts it references in its definition (dependency graph)
 3. **Identify consolidation candidates.** A concept should be consolidated if:
-   - It is defined in one module but referenced by specs in another module (currently shared via `exported_concepts`)
+   - It is defined in one module but referenced by functional specs in another module (currently shared via `exported_concepts`)
    - It is duplicated across multiple modules
    - It is a foundational domain concept that logically belongs in a shared vocabulary
 4. **Identify concepts that should stay local.** A concept should remain in its module if:
-   - It is only used within that single module's specs and definitions
+   - It is only used within that single module's functional specs and definitions
    - It is an internal implementation detail not meaningful outside that module
 
 ## Phase 2 — Plan the Consolidation
@@ -71,7 +71,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.
 
@@ -111,9 +111,9 @@ 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.
+2. Verify the downstream module's ***plain can still resolve all concept references.
 
 ## Phase 4 — Verify
 
@@ -140,7 +140,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
 
@@ -164,7 +164,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
@@ -174,7 +174,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
 
@@ -185,8 +185,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/genome/skills/convert-old-syntax/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: convert-old-syntax
+description: >-
+  Convert one module from the old ***plain syntax - functional specs as `- `
+  bullets, acceptance tests nested under them - to `# <func-id>` headings and
+  test plain files, word for word, the ids confirmed by the person first. Use
+  when turri says a module is in the old ***plain syntax, or the person asks to
+  convert one. One run converts one module, the lowest of the chain first;
+  it never regenerates.
+allowed-tools: [read, ls, grep, find, change_plain, parse]
+metadata:
+  phases:
+    ids: "a func-id for each functional spec and a scenario-id for each acceptance test, proposed and confirmed"
+    rewrite: "the module and its test plain files, in one ***plain diff, word for word"
+    check: "parse, and which module is next"
+  gates:
+    - after: rewrite
+      review:
+        rubric: ./references/rubric.md
+        judges: 2
+        quorum: all
+        on_fail: retry
+        max_retries: 2
+        judge_tools: [read, ls, grep, find]
+---
+
+# Convert Old Syntax
+
+Moves one module from the old ***plain syntax to the new one: each functional spec a `# <func-id>` heading with its body, and its acceptance tests in its test plain file. Nothing is reworded, added or dropped, and nothing is regenerated. The chat runs it again for the next module, asking the person in between.
+
+## Steps
+
+### ids
+
+**Which module.** Convert one module in this run. When the person named one, start at the lowest module of its `requires` chain still in the old syntax - the first, from the bottom of the chain, whose functional specs are `- ` bullets - which may be the one they named. Read the modules of the chain as text to tell: a module in the old syntax has `- ` bullets right under `***functional specs***`, or `***acceptance tests***` nested in it, and no `# <func-id>` heading. Skip import modules, which have no functional specs, and the standard library's templates (`stdlib/...`): there is nothing in them to convert. When every module of the chain is in the new syntax already, change nothing: say so, and that the run is done.
+
+**Read the module as text,** with `read` - the parser refuses the old syntax, so `parse` cannot read it yet. Change nothing in this step.
+
+**Propose the ids:**
+- A func-id for each functional spec - each top-level `- ` bullet under `***functional specs***`: short kebab-case from what it means (`add-task`), lowercase letters, digits and hyphens only, unique in the module (`semantic-ids.md`)
+- A scenario-id for each acceptance test nested under one, the same way from its text, unique among that functional spec's acceptance tests
+
+Ask the person once, with `ask_user`: the whole list in its `context` - each func-id with the first words of its bullet, and under it each scenario-id with the first words of its acceptance test - and options to accept the list or change ids. When they change some, apply the changes and ask again with the new list, until they accept it. Ask nothing else.
+
+### rewrite
+
+Write the whole conversion as one `change_plain` diff, with the confirmed ids:
+
+- **The module.** Under `***functional specs***`, each bullet becomes its `# <func-id>` heading followed by its body: the bullet's text without its leading `- `, word for word. Its sub-bullets become `- ` bullets under that text, one level less indented, word for word and in the same order. Its nested `***acceptance tests***` are taken out of the module. The functional specs keep their order, one blank line between them. The frontmatter, every other section, the comments and any Liquid stay exactly as they are.
+- **Its test plain files,** one for each functional spec that has acceptance tests, at `tests/<module>/<func-id>.plain`: frontmatter `module:` (the module's file name without `.plain`) and `func_id:`, then `***conformance tests***`, then `***acceptance tests***` (`test-plain-files.md`). Each acceptance test of the functional spec becomes a scenario under `***acceptance tests***`: its `# <scenario-id>` heading followed by its text without its `- `, word for word, and its sub-bullets as `- ` bullets under it. `***conformance tests***` stays empty. A functional spec with no acceptance tests gets no test plain file: it has no scenarios.
+
+Nothing else: no word added, reworded or dropped, no conformance scenario, no fix to the ***plain however clear it seems. What the conversion shows to be wrong goes in the result, for the person to decide on later.
+
+The change regenerates nothing: a module built before func-ids is not built on until its chain is regenerated from scratch, which the chat asks the person for.
+
+The record for the review: the module as it was before the change, word for word as you read it; the confirmed ids; and every file the change wrote. When the review sends the step back, show the person what it found and your fix with `ask_user`, then write the fix with one `change_plain`.
+
+### check
+
+Run `parse` on the module and show what it says in your reply.
+
+When it reports an error the conversion made, show it to the person with `ask_user`, with the fix, and write the fix with one `change_plain`; then run `parse` again. An error the module had before the conversion stays for the person.
+
+End with the result:
+- the module converted, its functional specs and scenarios counted, and the files written
+- what `parse` said
+- the next module of the chain still in the old syntax, for the chat to convert with this skill again - or that the chain is done
+- that nothing was regenerated: once the whole chain is converted, its code in `plain_modules/` was built when functional specs were numbered, and the chain has to be regenerated from scratch - only with the person's go

package/genome/skills/convert-old-syntax/references/rubric.md

@@ -0,0 +1,11 @@
+# The conversion lost, changed and added nothing
+
+The artifact holds a module as it was in the old ***plain syntax, word for word, the func-ids and scenario-ids the person confirmed, and the files the conversion wrote. Read each file it names from disk, and check every criterion. One violation fails the review; name it, with the functional spec or scenario and the words that differ.
+
+1. **Every functional spec is there.** Each top-level `- ` bullet under `***functional specs***` of the module as it was is one `# <func-id>` heading in the module now, with the confirmed func-id, in the same order. No functional spec is missing, and none was added or split.
+2. **Every body is its bullet, word for word.** Under each heading, the text is the bullet's text without its leading `- `, word for word, and its sub-bullets follow as `- ` bullets, word for word and in the same order. Nothing is reworded, shortened, merged, reordered or added - not a word, not a full stop.
+3. **Every acceptance test is a scenario, word for word.** Each acceptance test nested under a bullet is a scenario under `***acceptance tests***` in that functional spec's test plain file: a `# <scenario-id>` heading with the confirmed scenario-id, then the acceptance test's text without its `- `, word for word, its sub-bullets as `- ` bullets.
+4. **Nothing was added to the tests.** No scenario that was not an acceptance test: `***conformance tests***` is empty in every test plain file, and `***acceptance tests***` holds only the converted acceptance tests.
+5. **A test plain file for every functional spec with acceptance tests, and none for the rest.** Each is at `tests/<module>/<func-id>.plain`, with frontmatter `module:` set to the module's name and `func_id:` to its func-id, then `***conformance tests***`, then `***acceptance tests***`, each heading at the start of a line. A functional spec with no acceptance tests has no test plain file - an empty one fails this point.
+6. **The rest of the module is untouched.** The frontmatter, `***definitions***`, `***implementation reqs***`, `***test reqs***`, comments and Liquid read exactly as they did, and no `***acceptance tests***` is left in the module.
+7. **The ids are well formed.** Every func-id and scenario-id is lowercase letters, digits and hyphens only; func-ids are unique in the module, and scenario-ids unique within their functional spec.