@turri-dev/cli 0.0.0-stage → 0.1.1

package/genome/rules/concise-specs.md

@@ -0,0 +1,80 @@
+---
+description: Conciseness and plain-language rules that keep .plain specs reviewable by a human
+---
+
+# Rules for keeping `.plain` specs concise
+
+These rules apply to every section, to concept explanations, and to acceptance tests. `concise-specs-examples.md` holds a worked BAD to GOOD pair for each failure mode named here, and `concise-specs-integration-examples.md` covers the failure modes specific to integration specs.
+
+## Why this matters
+
+- A spec is the source of truth, so a human has to be able to review it
+- A long, dense, or ornate spec is skipped rather than reviewed — an unreviewed spec is an unverified spec, however correct it happens to be
+- Length is not a proxy for rigor: a spec earns trust by being checkable, not by being thorough-looking
+- Conciseness is about removing what carries no information, never about removing required detail — the deterministic-interface, disambiguation, and testability rules always win (see `func-specs.md`)
+
+## Do not write the obvious
+
+Delete any line a competent reader would already assume. Ask of every line: *if this were missing, would anything be built differently?* If not, cut it.
+
+Do not write:
+
+- Restatements of a concept's own name (`:UserEmail: is the email address of a :User:.` adds nothing beyond what `definitions.md` already requires the concept to carry)
+- Universal software defaults: that invalid input is rejected, that errors are reported, that data is saved when saving is the point of the operation
+- Rationale, motivation, benefits, or background — the spec states what is, not why it was chosen
+- Standard behavior of a technology already named in `***implementation reqs***` (an HTTP framework parses HTTP; a database driver opens connections)
+- Restatements of a nearby bullet in different words, or of anything already stated in an `import`ed or `require`d module
+- Anything about work the spec is not about ("no changes to the existing UI")
+- Meta-commentary about the spec itself ("this spec is intentionally small", "as described above")
+
+Worked pairs for every item above — padding, rationale, defaults, technology behavior,
+meta-commentary, and duplication of an `import` — are in `concise-specs-examples.md`.
+
+## Use plain words
+
+- Prefer the shortest word that is still exact; a technical term needs to be exact, an elaborate one is not
+- Write short sentences: one clause plus, at most, one qualifier
+- Use the same word for the same thing every time — synonym variety reads as two different things
+- Do not use adverbs and adjectives that no test can check: `robust`, `seamless`, `efficient`, `scalable`, `comprehensive`, `modern`, `properly`, `gracefully`, `as appropriate`, `where applicable`, `best practices`. Either state the checkable fact (`a response is returned within 200 ms`) or delete the word
+- Do not hedge: `should ideally`, `may optionally`, `typically`, `generally`, `if possible`. A spec states one behavior; a hedge tells the renderer to guess
+
+| Do not write | Write |
+|---|---|
+| utilize, leverage | use |
+| facilitate, enable the ability to | let, or name the action |
+| in order to | to |
+| prior to / subsequent to | before / after |
+| in the event that | if |
+| is responsible for handling | handles |
+| performs the validation of | validates |
+| a plurality of | several, or a number |
+| terminate, initiate | stop, start |
+| functionality for X | X |
+
+## Keep the shape small
+
+- One statement per bullet, one bullet per fact (see `bullet-continuation.md`)
+- Nest a sub-bullet only to remove a real ambiguity; a sub-bullet that merely elaborates is filler
+- Consecutive specs that share a subject are usually one spec: if a top-level bullet only tells part of the story of one operation, merge the set, lead with the operation's result, and demote the steps and failure modes to sub-bullets (see *One operation fragmented into several specs* in `concise-specs-integration-examples.md`)
+- Tables, prose paragraphs, and code blocks do not belong in a section; external artifacts are linked from `resources/` (see `linked-resources.md`)
+- A bullet that answers more than one of *what is it*, *what does it do*, *how is it built*, and *how is it tested* is not one fact — split it across the sections that own those facts, which reads better and is the only way the renderer sees each part (see `module-structure.md`, and *Split one crowded bullet across its owning sections* in `concise-specs-examples.md`)
+
+## Terse is not a defect
+
+A finished spec usually reads as abrupt: clipped bullets, no connective tissue, no lead-ins. That is the intended shape, not something to smooth out afterwards.
+
+- Add a word only to make a line correct, unambiguous, or checkable — never to make it read better
+- Do not merge short bullets into one sentence for rhythm, and do not open a section or a bullet with a lead-in
+- The bar is the other rules — correct, intent intact, reviewable, testable. A spec that clears them is finished however clipped it sounds
+- Filler is not neutral: the renderer reads every line as a requirement, so a line written for flow can invent one
+
+## Review pass before writing to disk
+
+Read the drafted lines once more and apply, in order:
+
+1. **The deletion test** — cut every line whose removal would change nothing about what gets built
+2. **The word test** — replace every ornate word with a plain one, and delete every uncheckable adjective, adverb, and hedge
+3. **The duplication test** — cut anything already stated in this file, an `import`, or a `requires` chain
+4. **The read-aloud test** — a line you cannot read aloud in one breath is either two facts or one padded one
+
+If a cut would remove an interface detail, a boundary case, or a disambiguation, keep the fact and shorten the wording instead — see *Do not over-cut* in `concise-specs-examples.md` for what a spec cut past its content looks like.

package/genome/rules/definitions.md

@@ -0,0 +1,107 @@
+---
+description: Rules for writing ***definitions*** sections in .plain files
+---
+
+# Rules for writing `***definitions***`
+
+When writing or editing a `***definitions***` section in a `.plain` file, always follow these rules:
+
+## Concept syntax
+- Wrap concept names in colons: `:ConceptName:`
+- Use CamelCase starting with an uppercase letter
+- Valid characters: letters, digits, `+`, `-`, `.`, `_`
+
+## Uniqueness
+- Concept names must be globally unique across the spec and all its imports
+- Check for collisions with concepts coming from `import` and `requires` modules before adding
+
+## Predefined concepts (do not redefine)
+- ***plain ships several predefined concepts that are available in every module without being defined
+- Never add a `***definitions***` entry for any of them — the renderer treats redefinitions as conflicts
+
+| Predefined concept | Meaning |
+|--------------------|---------|
+| `:plainDefinitions:` | Content of the `***definitions***` section |
+| `:plainImplementationReqs:` | Content of the `***implementation reqs***` section |
+| `:plainFunctionality:` | Content of the `***functional specs***` section |
+| `:plainTestReqs:` | Content of the `***test reqs***` section |
+| `:Implementation:` | The system implementing `:plainFunctionality:` |
+| `:plainImplementationCode:` | The generated implementation code |
+| `:UnitTests:` | Auto-generated unit tests for individual functionalities |
+| `:ConformanceTests:` | Auto-generated tests verifying conformance to the spec |
+| `:AcceptanceTest:` / `:AcceptanceTests:` | Tests validating specific aspects of the implementation |
+
+## Conciseness
+- A definition is one plain sentence plus, where needed, its attributes — see `concise-specs.md`
+- Never restate the concept name as its own definition, and never explain why the concept exists
+
+## Define before use
+- A concept must be defined before it is referenced in any section (definitions, implementation reqs, functional specs, test reqs)
+- Sources of definitions: the module's own `***definitions***`, an `import`ed module's definitions, or a `require`d module's `exported_concepts`
+
+## No circular references
+- Concept references must not form cycles — if A references B, then B must not reference A (directly or indirectly)
+- Insert each concept after any concepts it references
+
+Bad — circular:
+
+```plain
+***definitions***
+
+- :Customer: is a user who has placed at least one :Order:.
+
+- :Order: is placed by :Customer: and contains :OrderItem: entries.
+```
+
+`:Order:` references `:Customer:`, and `:Customer:` references `:Order:`. Fix by removing the back-reference:
+
+```plain
+***definitions***
+
+- :Customer: is a user of the system.
+
+- :Order: is placed by :Customer: and contains :OrderItem: entries.
+```
+
+## Exported concepts are not transitive
+- If module A exports a concept and module B `requires` A, a module C with `requires: [B]` does **not** gain access to A's exports
+- To use an ancestor's exports, list that ancestor in `requires` as well; concepts shared more broadly belong in a common import module
+
+## Description quality
+- Descriptions must be clear, concise, and language-agnostic
+- Nest attributes and constraints as sub-bullets
+- Do not use programming language constructs (generics, annotations, framework types) in definitions
+
+## Concept granularity and technical components
+- Definitions are not restricted to high-level domain objects. When an implementation warrants abstract, technical, or infrastructural components to clarify responsibilities, it is desired and encouraged to define them.
+- Group related technical concepts using the `of` keyword or by stating their relationship explicitly.
+
+Example of defining technical components alongside their behavior:
+
+```plain
+***definitions***
+
+- :CsvToJsonConverter: bidirectionally converts csv and json strings.
+
+- :CsvToJson: of :CsvToJsonConverter: converts a list of csv strings (e.g., "value1,value2,value3") to a list of json strings (e.g., "{\"key1\":\"value1\"}").
+
+- :JsonToCsv: of :CsvToJsonConverter: converts a list of json strings (e.g., "{\"key1\":\"value1\"}") to a list of csv strings (e.g., "value1,value2").
+
+- :StorageService: is an abstraction for a remote blob storage backend.
+
+- :CsvFileWriter: writes CSV rows to local files, automatically rotates to new files when size limits are reached, and flushes completed files to :StorageService:.
+
+- :CsvFileReader: reads CSV rows in a batched manner.
+
+- :CsvJoiner: joins csvs and uses :CsvFileWriter: to create the merged CSV.
+```
+
+## Format
+
+```plain
+***definitions***
+
+- :ConceptName: is a description of what it represents.
+  - Attribute one (required)
+  - Attribute two (optional)
+```

package/genome/rules/examples/integration-embedded-testing/run_conformance_tests_java.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+
+# Export Java 21
+#export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"
+#export PATH="$JAVA_HOME/bin:$PATH"
+echo "JAVA_HOME: $JAVA_HOME"
+
+# Check if build folder name is provided
+if [ -z "$1" ]; then
+  printf "Error: No build folder name provided.\n"
+  printf "Usage: $0 <build_folder_name> <conformance_tests_folder>\n"
+  exit 1
+fi
+
+# Check if conformance tests folder name is provided
+if [ -z "$2" ]; then
+  printf "Error: No conformance tests folder name provided.\n"
+  printf "Usage: $0 <build_folder_name> <conformance_tests_folder>\n"
+  exit 1
+fi
+
+current_dir=$(pwd)
+
+# Resolve the conformance tests folder to an absolute path ($2 may be relative
+# on older renderers; newer renderers pass it as an absolute path).
+case "$2" in
+  /*) CONFORMANCE_TESTS_SOURCE="$2" ;;
+  *)  CONFORMANCE_TESTS_SOURCE="$current_dir/$2" ;;
+esac
+
+# Host-relative paths of the module, as declared in ***implementation reqs***.
+# Replace the placeholders with the module's integration source path and its
+# :UnitTests: source path (the same paths run_unittests_java.sh copies to).
+INTEGRATION_CODE_PATH="<placeholder for integration code>"
+INTEGRATION_TESTS_PATH="<placeholder for integration code tests>"
+
+# Host codebase root: read from HOST_CODEBASE_ROOT (the one configured fact),
+# defaulting to three levels up from this script.
+MAIN_PROJECT_FOLDER="${HOST_CODEBASE_ROOT:-$(cd "$(dirname "$0")/../../.." && pwd)}"
+
+# Stage the generated code into the host codebase (same copy as run_unittests_java.sh)
+if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+  printf "Copying generated code to main project folder: $MAIN_PROJECT_FOLDER\n"
+fi
+
+# Check if the main project folder exists
+if [ ! -d "$MAIN_PROJECT_FOLDER" ]; then
+  echo "Error: Main project folder '$MAIN_PROJECT_FOLDER' does not exist."
+  exit 2
+fi
+
+# clean existing code of this module only from the main project folder
+rm -rf "$MAIN_PROJECT_FOLDER/$INTEGRATION_CODE_PATH"/*
+rm -rf "$MAIN_PROJECT_FOLDER/$INTEGRATION_TESTS_PATH"/*
+
+# copy generated code to the main project folder
+mkdir -p "$MAIN_PROJECT_FOLDER/$INTEGRATION_CODE_PATH"
+mkdir -p "$MAIN_PROJECT_FOLDER/$INTEGRATION_TESTS_PATH"
+cp -R "$1/$INTEGRATION_CODE_PATH"/* "$MAIN_PROJECT_FOLDER/$INTEGRATION_CODE_PATH"
+cp -R "$1/$INTEGRATION_TESTS_PATH"/* "$MAIN_PROJECT_FOLDER/$INTEGRATION_TESTS_PATH"
+
+# Move to the host codebase and build / install it, so the conformance project
+# resolves this build from the local Maven repository (~/.m2), not a stale one.
+echo "Moving to: $MAIN_PROJECT_FOLDER"
+cd "$MAIN_PROJECT_FOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Java build folder '$MAIN_PROJECT_FOLDER' does not exist.\n"
+  exit 2
+fi
+
+# Remove target directory to avoid conflicts with a previous build
+rm -rf ./target || echo "Warning: some files may be locked"
+
+# -DskipTests is legitimate here: this step only installs the host build;
+# the conformance tests run below.
+echo "Running maven install in the host codebase..."
+mvn clean install -Dspring-boot.repackage.skip=true -DskipTests
+
+install_exit_code=$?
+if [ $install_exit_code -ne 0 ]; then
+  echo "Error: Maven install failed in the host codebase with exit code $install_exit_code..."
+  exit 69
+fi
+
+# Scratch folder lives in the system temp directory so no build debris is left
+# inside the project. It is removed again when the script exits.
+CONFORMANCE_TESTS_FOLDER="/tmp/java_conformance"
+
+trap 'rm -rf "$CONFORMANCE_TESTS_FOLDER"' EXIT
+
+printf "Preparing Java conformance tests subfolder: $CONFORMANCE_TESTS_FOLDER\n"
+
+# Check if the conformance tests scratch folder exists
+if [ -d "$CONFORMANCE_TESTS_FOLDER" ]; then
+  # Find and delete all files and folders
+  find "$CONFORMANCE_TESTS_FOLDER" -mindepth 1 -exec rm -rf {} +
+
+  if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+    printf "Cleanup completed.\n"
+  fi
+else
+  # print the current directory
+  printf "Current directory: $(pwd)\n"
+
+  printf "Subfolder does not exist. Creating it...\n"
+  mkdir -p $CONFORMANCE_TESTS_FOLDER
+fi
+
+printf "Copying all files and folders from $CONFORMANCE_TESTS_SOURCE to $CONFORMANCE_TESTS_FOLDER...\n"
+cp -R "$CONFORMANCE_TESTS_SOURCE"/* $CONFORMANCE_TESTS_FOLDER
+
+# Move to the subfolder
+printf "Moving to $CONFORMANCE_TESTS_FOLDER...\n"
+cd "$CONFORMANCE_TESTS_FOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Java conformance tests folder '$CONFORMANCE_TESTS_FOLDER' does not exist.\n"
+  exit 2
+fi
+
+echo "Running maven install in the conformance tests folder..."
+mvn clean install -DskipTests
+
+
+if [ $? -ne 0 ]; then
+  exit 2
+fi
+
+echo "Running maven test in the conformance tests folder..."
+
+output=$(mvn test --no-transfer-progress 2>&1)
+exit_code=$?
+
+echo "Finished running maven test in the conformance tests folder..."
+
+# Check if no tests were run
+if echo "$output" | grep -q 'Tests run: [1-9][0-9]*, Failures: 0, Errors: 0, Skipped: 0'; then
+    echo "All tests passed"
+    echo "$output"
+    exit $exit_code
+else
+    # Check if no tests were run
+    if echo "$output" | grep -q 'Tests run: 0, Failures: 0, Errors: 0, Skipped: 0'; then
+        echo "Tests run: 0"
+        echo "Error: No tests were executed (Tests run: 0)"
+        echo "You are seeing this cause the following appeared in the output: Tests run: 0, Failures: 0, Errors: 0, Skipped: 0"
+    else
+        echo "Some tests failed, had errors, or were skipped. This is not allowed. All tests must pass."
+    fi
+fi
+
+# If there was an error, print the output and exit with the error code
+if [ $exit_code -ne 0 ]; then
+    echo "Error: Maven test failed in the conformance tests folder with exit code $exit_code..."
+    echo "$output"
+    exit $exit_code
+fi
+
+echo "Finished running conformance tests..."
+echo "$output"
+# Echo the original exit code of the unittest command
+exit $exit_code

package/genome/rules/examples/integration-embedded-testing/run_unittests_java.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# Export Java 21
+#export JAVA_HOME="/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home"
+#export PATH="$JAVA_HOME/bin:$PATH"
+echo "JAVA_HOME: $JAVA_HOME"
+
+# Check if subfolder name is provided
+if [ -z "$1" ]; then
+  echo "Error: No subfolder name provided."
+  echo "Usage: $0 <subfolder_name>"
+  exit 1
+fi
+# FIX: Changed this line from "../../" to "../../.." to go up three levels to the main project folder
+MAIN_PROJECT_FOLDER="$(cd "$(dirname "$0")/../../.." && pwd)"
+
+if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+  printf "Copying generated code to main project folder: $MAIN_PROJECT_FOLDER\n"
+fi
+
+# Check if the main project folder exists
+if [ ! -d "$MAIN_PROJECT_FOLDER" ]; then
+  echo "Error: Main project folder '$MAIN_PROJECT_FOLDER' does not exist."
+  exit 2
+fi
+
+# clean existing code from the main project folder
+rm -rf $MAIN_PROJECT_FOLDER/<placeholder for integration code>/*
+rm -rf $MAIN_PROJECT_FOLDER/<placeholder for integration code tests>/*
+
+# copy generated code to the main project folder
+# FIX: added the mkdir lines otherwise it complains that the cp destintation directory does not exist
+mkdir -p $MAIN_PROJECT_FOLDER/<placeholder for integration code>
+mkdir -p $MAIN_PROJECT_FOLDER/<placeholder for integration code tests>
+cp -R $1/<placeholder for integration code>/* $MAIN_PROJECT_FOLDER/<placeholder for integration code>
+cp -R $1/<placeholder for integration code tests>/* $MAIN_PROJECT_FOLDER/<placeholder for integration code tests>
+
+# Move to the subfolder
+# FIX: added this line to print the current directory to help the LLM
+echo "Moving to: $MAIN_PROJECT_FOLDER"
+cd "$MAIN_PROJECT_FOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Java build folder '$MAIN_PROJECT_FOLDER' does not exist.\n"
+  exit 2
+fi
+
+
+# Execute all Java unittests in the subfolder
+echo "Running Java unittests in $1..."
+mvn test -Dtest='<placeholder for integration code tests package>.**.*Test' checkstyle:check

package/genome/rules/exported-concepts.md

@@ -0,0 +1,39 @@
+---
+description: Rules for using exported_concepts in .plain files
+---
+
+# Rules for `exported_concepts`
+
+When adding or editing `exported_concepts` in a `.plain` file's frontmatter, always follow these rules:
+
+## What exported_concepts does
+- `exported_concepts` declares which concepts from this module are visible to modules that `require` it
+- Concepts not listed in `exported_concepts` are internal to the module and invisible to downstream modules
+- Only modules that use `requires` receive exported concepts — `import` gives access to all definitions, not just exports
+- An exported concept is visible with its full definition text
+
+## When to use it
+- Use `exported_concepts` on any module that other modules will `require`
+- List only the concepts that downstream modules actually need to reference
+- Keep the exported surface small — expose only what is necessary
+
+## Concepts must be defined
+- Every concept listed in `exported_concepts` must be defined in the module's own `***definitions***` section
+- Do not export concepts that are not defined in the module
+
+## Exports are not transitive
+- If module A exports `:Foo:` and module B `requires` A, a module C with `requires: [B]` does **not** gain access to `:Foo:`
+- If module C also needs `:Foo:`, it should list A in its `requires` as well (`requires: [A, B]`) or get `:Foo:` through a common import module
+
+## Format
+
+```plain
+---
+import:
+  - airplain
+exported_concepts: [":User:", ":JwtToken:"]
+description: Exports User and JwtToken for downstream modules
+---
+```
+
+List concepts as a YAML array with each concept in `:ConceptName:` notation.

package/genome/rules/func-specs.md

@@ -0,0 +1,129 @@
+---
+description: Rules for writing ***functional specs*** and ***acceptance tests*** in .plain files
+---
+
+# Rules for writing `***functional specs***`
+
+When writing or editing a `***functional specs***` section in a `.plain` file, always follow these rules:
+
+## Voice
+- Write each functional spec as a **statement of fact** — present tense, indicative mood — describing what the software *is* or *does* once built, not as a command telling a developer what to build
+- **Name a concrete subject**: an actor (`A :User: can …`), a named component or concept (`:PdfRenderer: lays out …`, `:Order: processing depends on …`), or the affected data in passive voice (`All :Resource: items are returned`)
+- **Avoid the vague subject "The system …"** — it says nothing about *which* part does the work. Prefer the concrete component/concept, or passive voice with the affected concept as the subject
+- **Never open a spec with an imperative** like "Implement …", "Add …", "Create …", "Show …", "Display …", "Build …" — those read as instructions, not specifications
+- Do **not** use "should" / "should be able to" in a functional spec — that is requirement-modal voice; state the fact directly
+
+BAD — imperative commands, or the vague "The system":
+
+```plain
+***functional specs***
+
+- Implement the entry point for :App:.
+
+- The system shows :TaskList:.
+
+- Add :Task:.
+```
+
+GOOD — statements of fact with concrete subjects:
+
+```plain
+***functional specs***
+
+- :App: has an entry point.
+
+- The :TaskList: is displayed.
+
+- A :User: can add a :Task:. Only valid :Task: items are added.
+```
+
+## Conciseness
+- A functional spec that a human will not read is not reviewed, so every spec must be as short as its content allows — see `concise-specs.md`
+- Cut anything obvious, any rationale, and every uncheckable adjective; keep every interface detail, boundary case, and disambiguation
+- Shorten the wording, never the facts: the rules below always win over brevity
+
+## Complexity limit
+- The complexity limit is about breaking software into small, independently understandable behavior slices that people and AI can reason about, implement, and test reliably
+- The current mechanism for enforcing the complexity limit is that each functional spec must imply a **maximum of 200 changed lines of code**.
+- Smaller slices produce focused test failures, reduce hidden coupling and regression surface, and make review and incremental rendering more predictable
+- If a spec is too large, use `break-down-func-spec` to split it into multiple smaller, independent specs
+- Use `analyze-if-func-spec-too-complex` to verify before inserting
+- Use `analyze-func-specs` to check a spec (or a batch of specs) against all relevant existing specs in a single batched call; use `resolve-spec-conflict` for each conflicting pair it reports
+
+## First-spec bootstrap cost
+- The first functional spec in a new root module carries implicit implementation cost even when its text describes little behavior
+- The renderer may need to create the project structure, package metadata, framework configuration, entry point, initial source files, and unit-test infrastructure before implementing the behavior
+- Count that bootstrap work toward the 200-changed-line limit; it is not free setup outside the spec
+- Make the first spec the module's simplest useful, independently observable capability
+- The first spec must still imply a testable outcome; setup alone is not a functional spec
+- Prefer one minimal entry point or public operation with a deterministic result that can be invoked and verified
+- Defer persistence, integrations, multiple interfaces, branching workflows, and cross-cutting behavior until later specs can build on the generated baseline
+- This extra bootstrap cost applies when no previous implementation baseline exists; a module that continues from a `requires` module may already inherit the necessary scaffold
+
+## Chronological ordering
+- Specs are rendered incrementally, top to bottom
+- The renderer has **no knowledge of future specs** — only previously rendered specs are in context
+- A new spec can reference behavior from earlier specs but cannot assume anything about specs that come after it
+- Functional specs from `requires` modules are treated as previous requirements — transitively, across the whole ancestor chain
+
+## No conflicts
+- The new spec must not contradict any existing functional spec
+- Before adding, review all existing specs and verify compatibility
+- If ambiguity exists, add explicit detail to eliminate any conflicting interpretation
+
+## Language agnosticism
+- Write in terms of behavior, concepts, and domain logic
+- Avoid language-specific terminology: generics syntax, framework annotations, language-specific collection types, decorator syntax, base-class keywords, framings like "POJO" or "dataclass"
+- General technical terms that are not language-specific are fine: null values, JSON types, HTTP status codes, REST endpoints, etc.
+- **Naming concrete components is encouraged.** Functional specs can and should refer to concrete domain components, services, or entities (e.g., `:PaymentProcessor:`, `:UserRepository:`, `:DataConverter:`) and their operations (e.g., `:ChargeCard:`, `:FindById:`), pinning down their inputs, outputs, and error behavior. Those names are part of the public contract and survive a language switch. What they must **not** do is bake in how the contract is realized (`@staticmethod`, `class Foo extends Bar`, `List<T>`, `async def`, etc.)
+- **Litmus test:** if the project switched from Python to Java (or vice versa), would the functional spec read correctly with only `***implementation reqs***` updated? If yes, the spec is language-agnostic. If the spec itself would need rewording, the construct belongs in implementation reqs.
+
+## Disambiguation
+- Each functional spec must be unambiguous — the renderer should have only one reasonable interpretation
+- If a single line is not enough to fully disambiguate the behavior, use **nested sub-bullets** to add detail
+- Nested lines clarify the parent spec — they do not introduce separate functionality
+- Even with nested detail, the spec must still imply ≤ 200 lines of code
+
+## Testability
+- Every functional spec must describe behavior that can be verified through an observable interface
+- State the triggering input or action and the deterministic outcome a test can observe
+- Include relevant outputs, state changes, errors, or externally visible side effects
+- Do not rely on generated implementation details as the only way to verify the behavior
+- If a black-box conformance test cannot be derived from the spec, make the behavior more explicit
+- Testability does not require an acceptance test; acceptance tests are reserved for full workflows
+
+## Deterministic interface
+- Specs must be detailed enough that a developer can use the built software without reading the generated code
+- All external interfaces must be explicit: REST endpoint paths and HTTP methods, CLI command names and arguments, file formats, message schemas, etc.
+- Never leave interface details up to the renderer's discretion
+
+## Encapsulation
+- Functionality must be self-contained in the spec text
+- `requires` modules only pass on functional specs and `exported_concepts` — never implementation reqs, so do not rely on implementation reqs to convey behavior
+- Behavior that downstream modules need must be expressed in functional specs, not elsewhere
+
+## Acceptance tests
+- Nest `***acceptance tests***` under a functional spec when verification criteria are needed
+- Each acceptance test must be a **full workflow test** — a specific scenario that exercises the functional spec end-to-end, not a unit-level check of a single field or condition
+- Do not restate the obvious behavior from the functional spec — simple, direct verifications are already auto-generated as conformance tests. Acceptance tests must go beyond that: multi-step workflows, interactions between concepts, edge-case scenarios, or end-to-end sequences that prove the feature works in a realistic context
+- Each acceptance test must be a direct logical consequence of the parent spec — it illustrates, not extends
+- Acceptance tests must describe concrete, verifiable outcomes — not vague qualities
+- Acceptance tests must not contradict, narrow, or extend beyond the parent spec
+
+## Format
+
+```plain
+***functional specs***
+
+- :App: has an entry point.
+
+- A :User: can add a :Task:. Only valid :Task: items are added.
+
+- A :User: can send a :Message: to a :Conversation:.
+  - A :Message: must have non-empty content.
+  - The :Message: is appended to the end of the :Conversation:.
+  - All :Participant: members of the :Conversation: can see the new :Message:.
+
+  ***acceptance tests***
+  - Sending a :Message: to a :Conversation: with three participants should make the message visible to all three.
+```

package/genome/rules/impl-reqs.md

@@ -0,0 +1,68 @@
+---
+description: Rules for writing ***implementation reqs*** sections in .plain files
+---
+
+# Rules for writing `***implementation reqs***`
+
+When writing or editing an `***implementation reqs***` section in a `.plain` file, always follow these rules:
+
+## HOW, not WHAT
+- Implementation reqs describe **how** the software should be built, not **what** it should do
+- Observable behavior (endpoints, business rules, user-facing features) belongs in `***functional specs***`
+- Internal structure, technology choices, and coding guidance belong here
+
+## `:UnitTests:` lives here (hard rule)
+- **Everything** about `:UnitTests:` goes in `***implementation reqs***` — paths, approach, packages, framework, conventions, fixtures, mocking policy, file layout, naming, lint / static-analysis gates
+- `:UnitTests:` are part of the generated codebase (they sit inside `plain_modules/<module>/code/` alongside the implementation), so requirements that shape them are implementation reqs by definition
+- The unit-test generator reads **only** `***implementation reqs***` — anything about `:UnitTests:` placed elsewhere (e.g. `***test reqs***`) is silently ignored
+- Author each `:UnitTests:` requirement via `add-implementation-requirement` and phrase it in terms of `:UnitTests:` so the partition stays visible at a glance
+
+## What belongs here
+- Technology choices: language, framework, runtime version
+- Architectural constraints: patterns, layering, dependency rules
+- Coding standards: naming conventions, style guidelines
+- Data formats: serialization, encoding, transformation rules
+- Error handling: strategies, retry logic, exception hierarchies
+- Algorithm descriptions: specific approaches when behavior alone is insufficient
+- Performance guidance: memory constraints, streaming requirements, batching strategies
+- Language-specific constructs: generics, annotations, framework-specific types and idioms
+- **Unit-test guidance: framework, structure, mocking conventions, file layout** — unit tests are part of the generated codebase, so requirements that shape them are implementation reqs
+
+## What does NOT belong here
+- Behavior and features → `***functional specs***`
+- Concept definitions → `***definitions***`
+- **Conformance-test guidance** → `***test reqs***`
+- **Acceptance-test scenarios** → `***acceptance tests***` nested under the relevant functional spec
+
+## Unit tests vs conformance tests (common mistake)
+- Unit-test guidance (`:UnitTests:` framework, structure, mocking) goes **here**, not in `***test reqs***`
+- `***test reqs***` is exclusively for `:ConformanceTests:` — framework, execution command, mocking policy, environment setup
+- Putting unit-test guidance in `***test reqs***` is one of the most common authoring mistakes; the rendered code will silently miss those requirements because the unit-test generator only reads `***implementation reqs***`
+- Do not link the unit testing script here (or anywhere in the specs; a link to it is ignored). turri finds it in the project root - `unittests-script:` in `config.turri.yaml`, else the one `run_unittests*.sh` in the root, else the one in `test_scripts/` - and shows it to the coding agent itself. Describe the framework and run command here in words
+
+## Encapsulation warning
+- `requires` modules only pass on functional specs and `exported_concepts` — never implementation reqs
+- If downstream modules need certain behavior to be visible, express it in functional specs, not here
+
+## Conciseness
+- State each req in the fewest plain words that stay exact — see `concise-specs.md`
+- Do not restate the standard behavior of a technology this section already names
+
+## No duplication
+- Do not duplicate guidance already present in the file or its imports
+- Check imported modules before adding a new req
+
+## Concept references
+- Reference defined `:Concepts:` where they add clarity
+- All referenced concepts must already be defined in `***definitions***`
+- Make the component a req constrains its subject; `:Implementation:` is the whole codebase, so use it only for a fact that holds everywhere — language, dependency manager, stack-wide convention
+
+## Format
+
+```plain
+***implementation reqs***
+- :Implementation: should be in Python 3.12.
+- :Implementation: should use pip for dependency management.
+- :ReportExporter: writes a :CsvFile: with streaming writes, never holding the full dataset in memory.
+- :UnitTests: should use pytest, run with `pytest tests/`.
+```