@turri-dev/cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,64 @@
+---
+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).
+allowed-tools: [read, write, edit, bash, 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.
+
+## 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 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 → `analyze-if-func-spec-too-complex`, then `break-down-func-spec`.
+- Two 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
+
+The bullet, section, or `.plain` file to resolve.
+
+## Workflow
+
+1. **Read the full `.plain` file** — every section, plus its `import` and `requires` chains, so an existing home for a fact is visible before a new one is written.
+2. **Identify the target** — one bullet, one section, or the whole file.
+3. **Decompose each bullet into atomic facts.** A clause joined by *and*, *which*, *so that*, or a comma often carries a second fact. Keep each fact in the author's own words for now; rewording comes at step 6.
+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. **Author each fact into its owning section** with the right edit skill — `add-concept`, `add-implementation-requirement`, `add-test-requirement`, `add-acceptance-test`. **Never hand-author `***functional specs***`**: a fact moving *into* that section goes through `add-functional-spec`, which runs the complexity and conflict analyzers for you.
+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.
+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
+
+- **`add-functional-spec` reports the moved fact is too complex** → the fact was a whole spec in disguise; run `break-down-func-spec` on it, then place the resulting specs.
+- **`add-functional-spec` 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.
+
+## Worked examples
+
+`concise-specs-examples.md` (*Split one crowded bullet across its owning sections*) shows one bullet carrying four kinds of fact. `concise-specs-integration-examples.md` works through the mechanism-versus-result cases — retry policy, idempotency, auth — which are where this comes up most.
+
+## Validation Checklist
+
+- [ ] Every fact from the original text appears in exactly one section, or was deliberately cut
+- [ ] No fact was reworded into a different meaning while being moved
+- [ ] Each moved fact names a subject that exists in the built system
+- [ ] Every fact moved into `***functional specs***` went through `add-functional-spec`
+- [ ] No `:UnitTests:` fact outside `***implementation reqs***`, no `:ConformanceTests:` fact outside `***test reqs***`
+- [ ] Sections are in canonical order and every referenced concept is defined before use
+- [ ] Emptied bullets and sections were removed, not left as stubs

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

@@ -0,0 +1,96 @@
+---
+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
+  functional spec (via `add-functional-spec` or `add-functional-specs`).
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Resolve Spec Conflict
+
+## 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 (via the `add-functional-spec` or `add-functional-specs` skill) appears to contradict an existing spec.
+- Two 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.
+
+### Step 2: Diagnose the Root Cause
+
+There are three possible outcomes — determine which one applies **before** making changes:
+
+| 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. |
+
+**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).
+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.
+
+Before (ambiguous):
+```plain
+***functional specs***
+
+- All :Resource: items are returned.
+
+- Only active :Resource: items are returned.
+```
+
+After (disambiguated):
+```plain
+***functional specs***
+
+- All :Resource: items are returned when no filter is specified.
+
+- 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 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 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.
+
+### 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.
+
+## Prevention (for use during add-functional-spec / add-functional-specs)
+
+Before adding a new 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.
+
+## 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
+- [ ] No new conflicts introduced by the fix
+- [ ] Chronological ordering preserved
+- [ ] All referenced `:Concepts:` are still defined

package/genome/skills/spawn/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: spawn
+description: >-
+  The quick twin of `brood`: asks only what the user wants to build and which stack to build it on -
+  one question, "you choose" among its answers - then writes the whole `***plain` spec on its own - the
+  stack, the unit tests and the product, feature by feature - making every choice itself where the user
+  said nothing, and queues each feature as a render spec
+  diff job the moment it is written. Conformance tests are off unless the user asks for them. No
+  interview beyond intent, no gates. The user then keeps
+  talking in the conversation, and every change they ask for is a spec diff: what is left to build
+  is worked out again from the spec. Use when the user wants to start a new project fast, or says to just build
+  it. For a full interview that settles the stack, the testing and every feature with the user, use
+  `brood`. Not for adding a feature to an existing project (use `bud`).
+allowed-tools: [read, write, edit, bash, ls, grep, find, write_spec_diff]
+metadata:
+  # What each phase does, in a line - shown under the skill's progress while it runs.
+  phases:
+    intent: "what you want to build, and which stack to build it on"
+    groundwork: "the language, frameworks, storage and architecture"
+    product: "writes the features one by one - each starts a regenerate pulse"
+  # It writes its spec changes one after another on its own: no answer between them.
+  paced: false
+---
+
+# Spawn
+
+Load the `***plain` syntax rules before writing anything - they are in the system prompt under
+`<plain-rules>`; read `genome/rules/<name>.md` for the full text of any rule you need to follow
+closely.
+
+## Role
+
+Act as a `***plain` spec writer who decides. The only output is `.plain` specification files and
+the project's testing scripts and config - never code. Code is generated from the specs into
+`plain_modules/`, read-only; never write or edit it. Say everything in terms of specs: "I'll put
+this in the spec."
+
+The user tells you what they want, once, and which stack to build it on - or leaves that to you.
+Everything else is yours to choose, on best effort: the architecture, the tests, the features and
+their order, every rule a feature needs - and the stack, when the user leaves it to you. Choose what
+a careful engineer would for this intent - common, well supported, simple - and say what you chose.
+Never ask about any of the rest. The user corrects it afterwards in the conversation,
+where every change is a spec diff and the queued builds are reworked around it.
+
+Read what is already there first: an existing `.plain` file, `config.turri.yaml` (or the old
+`config.yaml`, with no `config.turri.yaml`), `template/`,
+`test_scripts/`. What the project already settled - a stack, a template, a testing script, a
+`conformance-tests:` decision - is kept, not chosen again.
+
+## Reference
+
+- Templates go in `template/`; import paths omit the `template/` prefix. Resources go in `resources/`.
+- Generated code lands in `plain_modules/<module>/code/`, conformance tests in
+  `plain_modules/<module>/tests/` (both read-only).
+- One module, unless the intent needs two stacks - a web frontend and an API backend. Then two
+  modules side by side, neither requiring the other, sharing what they both mean through one
+  imported module in `template/`. Each is on a stack of its own, whose testing scripts are named in
+  `config.turri.<stack>.yaml` beside `config.turri.yaml` (`unittests-script:`, `conformance-tests-script:`) -
+  `config.turri.backend.yaml`, `config.turri.frontend.yaml`. A stack is chosen, never worked out: tell the
+  user to choose one with `/stack <stack>` (`--stack <stack>` on the command line) before building its part.
+
+## Steps
+
+### intent
+
+Find out what the user wants to build - the only thing you ask about.
+
+If what the user has already said answers it, do not ask again. Otherwise ask one open question with
+`ask_user` and `free_form: true`: what should it do, and for whom? Ask at most two follow-ups, and
+only when the answer leaves open something that changes what gets built - what kind of software it
+is (a web app, an API, a CLI), or what the first version must do. Never ask about testing, structure
+or details: those are yours.
+
+Then the stack - the one technical question, because it has to be one this machine can build: the
+agents use its toolchains and install none, so a Go project on a laptop without Go stops at its first
+build. `<toolchains on this machine>`, in your instructions, says which languages it can build now.
+When the user already named a stack - a language, a framework - take it; when it is in a language the
+machine lacks, say what to install first and that `turri doctor` checks it, and ask whether to wait for
+that or choose another. Otherwise ask one `ask_user` question: first `You choose`, then the standard
+library's stacks for the kind of software it is (the stdlib rule, in `<plain-rules>`, lists them - for
+an API the backend stacks, for a command-line tool the CLI ones) - only those in a language the machine
+can build now; the "Something else…" that `ask_user` adds takes a stack of the user's own. A product of two kinds - a web app and its API - is one question a module. `You choose` leaves it
+to you, as the groundwork step says.
+
+Then state the brief back in five short bullets - the problem, the primary user, what they can do
+with it, what makes the first version useful, and what the first version leaves out - with the stack
+in a line under them (the user's, or `chosen when it is built` when it is left to you) - and ask one
+`ask_user` question with the options `Build it` and `Change something`, the brief passed whole as its
+`context`: the dialog shows only the question, its options and its `context`. On a change, fold it in and
+ask again. Write nothing to disk in this step.
+
+### groundwork
+
+Set up everything the first build needs, on your own, with the ordinary file tools - no questions,
+nothing built, and `write_spec_diff` not used.
+
+1. **The module and its stack.** Create the `.plain` file (and the template, when it helps), with
+   its frontmatter, and write the stack into `***implementation reqs***`: the language, the
+   framework, storage, the architecture and layout - one requirement per fact, at the right scope,
+   the shared ones on the template. The stack is the user's, when they named or chose one; left to
+   you, choose what fits the intent - a mainstream stack, with the fewest moving parts - in a language
+   this machine can build now (`<toolchains on this machine>`). Follow
+   `genome/rules/impl-reqs.md`. When the standard library has a template
+   for it - a backend, a frontend, a command-line tool or a library (the stdlib rule, in `<plain-rules>`) -
+   import that template and write only what the module needs beyond it.
+2. **Unit tests.** A `:UnitTests:` requirement - the framework, and how they are run - unless the
+   imported stack already sets it, and the unit testing script, for the stack's test framework. Keep one turri already finds (named in `config.turri.yaml`, or the one
+   `run_unittests*.sh` in the root or `test_scripts/`); otherwise write
+   `test_scripts/run_unittests_<language>.sh` by following the `implement-unit-testing-script`
+   skill. Never link it from the specs. The script runs the stack's static checks with the unit
+   tests - the formatter in check mode, the linter, the type checker - and they count as the tests do.
+3. **Conformance tests: off**, so each feature is built fast. Keep a `conformance-tests:` decision
+   the project's config already holds - `config.turri.yaml`, or the old `config.yaml`. Otherwise write `conformance-tests: false` into
+   `config.turri.yaml`, changing nothing else in it - a project with only a `config.yaml` has it copied
+   to `config.turri.yaml` first, and `config.yaml` is never written - and write no `***test reqs***`, import no standard library
+   conformance template, and write no conformance testing script.
+   Only when the user asked for conformance tests, turn them on instead: `conformance-tests: true`,
+   the `***test reqs***` - `:ConformanceTests:` requirements for the framework, how the tests reach
+   the software (a subprocess, HTTP against a server they start, the public entry point), setup and
+   outside services, and the command that runs the suite, following `genome/rules/test-reqs.md`, or
+   the stack's standard library conformance template imported when the stack is from it -
+   and `test_scripts/run_conformance_tests_<language>.sh`, by following the
+   `implement-conformance-testing-script` skill, unless turri already finds one.
+
+Run `validate` on every module you wrote, and fix what it finds. Then say in a few lines what you
+chose - the stack, the architecture, the tests - and carry on. Do not ask for confirmation.
+
+### product
+
+Write the product, feature by feature, as spec diffs - on your own, without asking.
+
+1. **Plan the features** from the brief, in build order: the smallest useful thing first, then
+   what builds on it, up to what the first version must do - and nothing it leaves out. Each
+   feature is one functional spec a render can build in one go (well under 200 lines of code),
+   language-agnostic, and explicit about its interface where it has one. A feature too big for
+   that is two.
+2. **The description first.** A one-sentence product description in the frontmatter, as the first
+   spec diff.
+3. **Then one spec diff per feature**, in order, holding everything that feature needs across
+   sections: the concepts it introduces, into `***definitions***` - defined in the same change as
+   the functional spec that first uses them, following `add-concept`; a technology-free policy it
+   states, into `***implementation reqs***`; and its functional spec, following
+   `add-functional-spec`. Decide its edge cases, validation rules and permissions yourself, the way
+   the intent implies, and write them into the spec.
+4. **Write each with `write_spec_diff`** - a git diff of the `.plain` file(s): `diff --git
+   a/<file> b/<file>`, `--- a/<file>`, `+++ b/<file>`, then the hunks with a few lines of context,
+   paths from the project root. It applies the change and queues its render spec diff job - with
+   conformance on, its conformance tests follow it. Go straight on to the next feature -
+   never wait for a build. Never change a `.plain` file in this step by any other means.
+
+The step is done only once every feature you planned is written, one spec diff each. Never stop
+part-way to ask whether to go on, or which feature comes next: nobody answers in this step, and the
+skill ends when your turn does - so a question here leaves the product unwritten.
+
+Correct a change you find wrong once written with a diff and `fixes_earlier`, never by editing the
+file.
+
+End with the handover, in a few lines: the features in build order, the jobs they were queued as,
+that conformance tests are off unless they were asked for (turning them on later is one line in
+`config.turri.yaml`, `conformance-tests: true`, with the test reqs and the script added in the
+conversation), and what the user can do now - try each feature as its build lands (ask to try it, and the chat
+deploys it), and ask for any change in the conversation. A feature added, changed or dropped is one
+spec diff, and what is left to build is worked out again from the spec.

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plainlang/turri.git"
+  },
+  "homepage": "https://github.com/plainlang/turri#readme",
+  "bugs": "https://github.com/plainlang/turri/issues",
+  "description": "An agent that builds code from ***plain specifications, with harness-enforced review and conformance gates.",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "bin": {
+    "turri": "bin/turri.mjs"
+  },
+  "scripts": {
+    "cultivate": "tsx src/cultivate-cli.ts",
+    "typecheck": "tsc --noEmit",
+    "chat": "pi -e ./src/extension.ts",
+    "ask": "pi -p --no-session -e ./src/extension.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "mutation": "node scripts/mutation.mjs",
+    "conform": "tsx src/conform-cli.ts",
+    "regenerate": "tsx src/regenerate-cli.ts",
+    "validate": "tsx src/validate-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"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "^1.1.0",
+    "@earendil-works/pi-tui": "^1.1.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",
+    "remark-parse": "^11.0.0",
+    "typebox": "^1.3.7",
+    "unified": "^11.0.5"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^5.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "assets",
+    "bin",
+    "dist",
+    ".pi",
+    "genome",
+    "stdlib",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/stdlib/backend/common.plain

@@ -0,0 +1,25 @@
+---
+description: What every stdlib backend shares - a layered JSON HTTP service, its configuration, errors, logs and shutdown.
+---
+
+***implementation reqs***
+
+- :Implementation: is an HTTP service that serves JSON.
+- :Implementation: reads its configuration from environment variables once, at start, into one typed settings object that it passes to what needs it.
+  - Every setting has a default, except secrets.
+  - It listens on all interfaces, on the port in `PORT`, 8000 when unset.
+  - It does not start when a setting is missing or invalid: it writes which one to standard error and exits 1.
+- :Implementation: is layered: a handler parses and validates the request, calls a service, and turns its result into the response; a service holds the business logic and knows nothing of HTTP; data access sits behind repository interfaces that the services are given.
+- :Implementation: reports a failure of the business logic by raising one of its domain errors, which one place turns into the response.
+  - Not found is 404 with the code `not_found`, a conflict 409 `conflict`, invalid input 422 `validation_error`, a missing or bad credential 401 `unauthenticated`, a forbidden action 403 `forbidden`.
+- :Implementation: answers every error, the framework's own included, with the JSON body `{"error": {"code": "<snake_case code>", "message": "<text for a person>"}}`.
+  - A `validation_error` body adds `details`: one `{"field": "<dotted path>", "message": "<text>"}` per invalid field.
+- :Implementation: answers an unexpected failure with 500 and the code `internal_error`, never with its message or stack trace, and logs it at `ERROR` with the stack trace.
+- :Implementation: logs to standard output as JSON, one object per line, with `timestamp` (ISO 8601, UTC), `level`, `logger`, `message`, and the `request_id` of the request it belongs to.
+  - It logs at the level in `LOG_LEVEL`, `INFO` when unset.
+  - It logs one `INFO` line when each request ends, with `method`, `path`, `status` and `duration_ms`.
+  - It never logs a secret, a token, a password, or a request or response body.
+- :Implementation: takes each request's id from its `X-Request-ID` header, or makes a UUID v4 when it has none, and sends it back in `X-Request-ID`.
+- :Implementation: stops on SIGTERM or SIGINT: it stops taking connections and finishes the requests under way, for at most 10 seconds.
+- :UnitTests: cover the services directly, and each handler through the framework's in-process test client, never a listening port.
+- :UnitTests: replace every repository and outside service with an in-memory stand-in.

package/stdlib/backend/conformance/common.plain

@@ -0,0 +1,12 @@
+---
+description: How every stdlib backend's conformance tests run - against the service started from the built code, over HTTP only.
+---
+
+***test reqs***
+
+- :ConformanceTests: start the service from the built code as a separate process, on a free port given in `PORT`, and wait until it accepts connections, for at most 30 seconds.
+  - They build and start it exactly as its stack's implementation reqs say - "It builds with ..." and "It starts with ..." - from the built code's own folder.
+- :ConformanceTests: reach the service over HTTP only, and never import its code.
+- :ConformanceTests: check a failure by its status code and the `error.code` of its body, never by its message.
+- :ConformanceTests: stop the service when they finish, passing or failing.
+- :ConformanceTests: pass the formatter, the linter and the type checker of their language as the conformance testing script runs them, and are typed throughout where their language allows it.

package/stdlib/backend/conformance/go-gin.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/go-gin as a Go module with go test.
+---
+
+***test reqs***
+
+- :ConformanceTests: are a Go module of their own, using the `testing` package and `net/http`, run with `go test ./...`.

package/stdlib/backend/conformance/go-nethttp.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/go-nethttp as a Go module with go test.
+---
+
+***test reqs***
+
+- :ConformanceTests: are a Go module of their own, using the `testing` package and `net/http`, run with `go test ./...`.

package/stdlib/backend/conformance/java-springboot.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/java-springboot as a Maven project with JUnit 5 and the JDK's HttpClient.
+---
+
+***test reqs***
+
+- :ConformanceTests: are a Maven project of their own, using JUnit 5, AssertJ and the JDK's `HttpClient`, run with `mvn test`.

package/stdlib/backend/conformance/python-django.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/python-django in pytest and httpx.
+---
+
+***test reqs***
+
+- :ConformanceTests: use pytest and httpx, and run with `pytest`.

package/stdlib/backend/conformance/python-fastapi.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/python-fastapi in pytest and httpx.
+---
+
+***test reqs***
+
+- :ConformanceTests: use pytest and httpx, and run with `pytest`.

package/stdlib/backend/conformance/python-flask.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/python-flask in pytest and httpx.
+---
+
+***test reqs***
+
+- :ConformanceTests: use pytest and httpx, and run with `pytest`.

package/stdlib/backend/conformance/rust-axum.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/rust-axum as a Cargo package with reqwest.
+---
+
+***test reqs***
+
+- :ConformanceTests: are a Cargo package of their own, using tokio and reqwest, run with `cargo test`.

package/stdlib/backend/conformance/typescript-express.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/typescript-express in Vitest with fetch.
+---
+
+***test reqs***
+
+- :ConformanceTests: use Vitest and the built-in `fetch`, and run with `npx vitest run`.

package/stdlib/backend/conformance/typescript-fastify.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/typescript-fastify in Vitest with fetch.
+---
+
+***test reqs***
+
+- :ConformanceTests: use Vitest and the built-in `fetch`, and run with `npx vitest run`.

package/stdlib/backend/conformance/typescript-nestjs.plain

@@ -0,0 +1,9 @@
+---
+import:
+  - stdlib/backend/conformance/common
+description: Conformance tests for stdlib/backend/typescript-nestjs in Jest with fetch.
+---
+
+***test reqs***
+
+- :ConformanceTests: use Jest with ts-jest and the built-in `fetch`, and run with `npx jest`.

package/stdlib/backend/go-gin.plain

@@ -0,0 +1,18 @@
+---
+import:
+  - stdlib/lang/go
+  - stdlib/backend/common
+description: A backend in Go 1.25 with Gin, validator tags and slog.
+---
+
+***implementation reqs***
+
+- :Implementation: uses Gin, made with `gin.New()` and its own middleware only, in release mode.
+- :Implementation: keeps `main` in `cmd/server/`, and the rest in packages under `internal/`: `config`, `httpapi` - routes, handlers and middleware - `service` and `store`.
+  - It builds with `go build -o bin/server ./cmd/server`.
+- :Implementation: parses the environment into a `Config` struct in `internal/config`.
+- :Implementation: binds every request body with `ShouldBindJSON` and validates it with `binding` tags, answering a failure as `validation_error` with its `details`.
+- :Implementation: has handlers report an error with `c.Error(err)`, and one middleware write the error body for the last one, finding the domain error with `errors.As`, and recover from panics as `internal_error`.
+- :Implementation: logs with a `slog.JSONHandler` on standard output, with middleware that sets the request id and logs the request line; Gin's own logger is not used.
+- :Implementation: stops with `http.Server.Shutdown` when the context from `signal.NotifyContext` ends.
+- :UnitTests: use `net/http/httptest` against the Gin engine.

package/stdlib/backend/go-nethttp.plain

@@ -0,0 +1,18 @@
+---
+import:
+  - stdlib/lang/go
+  - stdlib/backend/common
+description: A backend in Go 1.25 with the standard library's net/http and slog, and no framework.
+---
+
+***implementation reqs***
+
+- :Implementation: uses the standard library's `net/http` with its method and path patterns, and no web framework.
+- :Implementation: keeps `main` in `cmd/server/`, and the rest in packages under `internal/`: `config`, `httpapi` - handlers, middleware and error writing - `service` and `store`.
+  - It builds with `go build -o bin/server ./cmd/server`.
+- :Implementation: parses the environment into a `Config` struct in `internal/config`.
+- :Implementation: decodes every request body with `encoding/json` with `DisallowUnknownFields`, into a struct whose `Validate() error` reports every invalid field.
+- :Implementation: writes handlers that return an error, adapted to `http.Handler` in one place that writes the error body, finding the domain error with `errors.As`.
+- :Implementation: logs with a `slog.JSONHandler` on standard output, with middleware that adds the request id to the request's context and logs the request line.
+- :Implementation: stops with `http.Server.Shutdown` when the context from `signal.NotifyContext` ends.
+- :UnitTests: use `net/http/httptest` for handlers and middleware.

package/stdlib/backend/java-springboot.plain

@@ -0,0 +1,19 @@
+---
+import:
+  - stdlib/lang/java
+  - stdlib/backend/common
+description: A backend in Java 21 with Spring Boot 3, Maven, Bean Validation and Logback JSON logs.
+---
+
+***implementation reqs***
+
+- :Implementation: uses Spring Boot 3 with Spring Web and Bean Validation, built with Maven through the Maven wrapper from `pom.xml` with the Spring Boot parent.
+- :Implementation: keeps its code in one base package with the subpackages `web` - controllers, request and response records - `service`, `repository`, `domain`, `config` and `error`.
+  - It builds with `./mvnw package` into one executable jar, started with `java -jar target/<artifact>.jar` - `pom.xml` sets `<finalName>${project.artifactId}</finalName>`, so the jar's name carries no version.
+- :Implementation: binds its settings from `application.yaml` into `@ConfigurationProperties` records, each set from an environment variable with its default, as `server.port: ${PORT:8000}`.
+- :Implementation: validates every request body with `@Valid`, and answers `MethodArgumentNotValidException` as `validation_error` with its `details`.
+- :Implementation: turns errors into responses in one `@RestControllerAdvice`, for the domain errors, Spring's own errors and `Exception`.
+- :Implementation: logs as JSON with Logback and logstash-logback-encoder, set up in `logback-spring.xml`.
+  - A `OncePerRequestFilter` puts the request id in the MDC as `request_id`, sends it back, and logs the request line.
+- :Implementation: shuts down with `server.shutdown: graceful` and a 10 second timeout per shutdown phase.
+- :UnitTests: cover services with plain JUnit, and controllers with `@WebMvcTest` and `MockMvc` with the services mocked, run with `./mvnw test`.

package/stdlib/backend/python-django.plain

@@ -0,0 +1,19 @@
+---
+import:
+  - stdlib/lang/python
+  - stdlib/backend/common
+description: A backend in Python 3.12 with Django 5, Django REST Framework, Gunicorn and python-json-logger.
+---
+
+***implementation reqs***
+
+- :Implementation: uses Django 5 with Django REST Framework, served by Gunicorn with 2 workers.
+- :Implementation: keeps the Django project in the package `config/` - `settings.py`, `urls.py`, `wsgi.py` - and each area of the domain in a Django app under `apps/`.
+  - Each app has `models.py`, `serializers.py`, `views.py` with DRF views, `services.py`, `urls.py`, and its migrations in `migrations/`.
+- :Implementation: reads its settings from the environment in `config/settings.py`, and its database from `DATABASE_URL` with dj-database-url, an SQLite file `db.sqlite3` when unset.
+  - It starts with `uv run python manage.py migrate --noinput && uv run gunicorn config.wsgi --bind 0.0.0.0:$PORT --workers 2`.
+- :Implementation: keeps the business logic in each app's `services.py`, never in a view or a serializer.
+- :Implementation: sets DRF's `EXCEPTION_HANDLER` to one function that turns the domain errors, DRF's exceptions and `Http404` into the error body, and DRF's `ValidationError` into `validation_error` with its `details`.
+- :Implementation: logs as JSON with python-json-logger, set up in `LOGGING` in `config/settings.py`, with a middleware that keeps the request id in a context variable, adds it to every record, and logs the request line.
+- :UnitTests: use pytest-django with DRF's `APIClient`, against a test database Django creates.
+  - `[tool.pytest.ini_options]` sets `DJANGO_SETTINGS_MODULE = "config.settings"`, so pytest-django finds the settings without an environment variable.