@turri-dev/cli 0.0.0-stage → 0.1.2-next.48dacfc

package/genome/skills/add-implementation-requirement/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: add-implementation-requirement
+description: >-
+  Add an implementation requirement to the ***implementation reqs*** section of
+  a ***plain spec file. Use when the user wants to add non-functional
+  requirements like technology choices, architectural constraints, coding
+  standards, data formats, error handling strategies, or any HOW-to-build
+  guidance to a .plain file.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Add Implementation Requirement
+
+## Workflow
+
+1. **Identify the target `.plain` file.** If ambiguous, ask the user.
+2. **Read the file** to understand existing implementation reqs, definitions, and functional specs.
+3. **Determine if this belongs in implementation reqs** — it must describe HOW to build, not WHAT to build (that goes in `***functional specs***`).
+4. **Draft the requirement** following the rules below.
+5. **Insert it** into the `***implementation reqs***` section.
+6. **Read the file again** to confirm correct placement and syntax.
+
+## What Belongs Here
+
+Implementation reqs are free-form instructions that steer code generation. Common contents:
+
+- **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
+
+## What Does NOT Belong Here
+
+- **Behavior and features** — those go in `***functional specs***`
+- **Concept definitions** — those go in `***definitions***`
+- **Conformance-test instructions** — those go in `***test reqs***`. Note: **unit-test instructions belong HERE**, not in `***test reqs***` — see *Unit-test guidance belongs here* below
+
+## Unit-test guidance belongs here
+
+**Everything about `:UnitTests:` goes in `***implementation reqs***`** — paths, approach, packages, framework (JUnit / pytest / Jest / Go's `testing` / …), conventions, fixtures, mocking policy, file layout, naming, lint / static-analysis gates. Unit tests are part of the generated codebase, so requirements that shape them are implementation reqs by definition.
+
+- The unit-test generator reads **only** `***implementation reqs***`; anything about `:UnitTests:` placed in `***test reqs***` is silently ignored
+- Phrase each `:UnitTests:` requirement in terms of the predefined `:UnitTests:` concept so the partition stays visible at a glance
+- `***test reqs***` is exclusively for `:ConformanceTests:` — see [`add-test-requirement`](../add-test-requirement/SKILL.md)
+
+## Key Principle: HOW vs WHAT
+
+`***implementation reqs***` describe HOW the software should be built.
+`***functional specs***` describe WHAT the software should do.
+
+If the requirement describes observable behavior (endpoints, business rules, user-facing features), it belongs in functional specs. If it describes internal structure, technology, or coding guidance, it belongs here.
+
+## Format
+
+Implementation reqs are bullet points in the `***implementation reqs***` section:
+
+```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.
+
+```
+
+Reference defined `:Concepts:` where they add clarity. Implementation reqs in non-leaf sections apply to all subsections.
+
+
+## Encapsulation Warning
+
+`requires` modules only receive functional specs from their dependencies — not implementation reqs. If downstream modules need certain behavior to be visible, that behavior must be expressed in functional specs, not here.
+
+## Validation Checklist
+
+- [ ] Describes HOW to build, not WHAT to build
+- [ ] All referenced `:Concepts:` are defined in `***definitions***`
+- [ ] Does not duplicate guidance already present in the file or its imports
+- [ ] Trimmed per `concise-specs.md`: plain words, no rationale, no standard behavior of a technology already named
+- [ ] Placed inside a `***implementation reqs***` section
+- [ ] No behavioral requirements that should be in `***functional specs***`

package/genome/skills/add-resource/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: add-resource
+description: >-
+  Add a linked resource (external file reference) to a ***plain spec. Use when
+  the user wants to reference a JSON schema, API spec, data file, or other
+  external file from within a functional spec, definition, or implementation
+  requirement.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Add Resource
+
+Linked resources are external files referenced from within a `.plain` spec using markdown link syntax. The file contents are passed to the renderer alongside the spec, providing additional context for code generation.
+
+## Workflow
+
+1. **Identify or create the resource file.** Keep it inside the project — the `resources/` directory is the conventional home; it does not have to sit next to the `.plain` file.
+2. **Add the markdown link** at the appropriate place in the spec.
+3. **Verify the file path** is relative to the `.plain` file location.
+4. **Read the file back** to confirm correct link syntax and path.
+
+## Format
+
+Use standard markdown link syntax inside any spec section:
+
+```plain
+***definitions***
+- :AuthData: is the authentication data structure.
+  - Its format is defined in the [auth schema](resources/auth_schema.json).
+
+***implementation reqs***
+- When transforming :BackupData:, use the JOLT transform.
+  - The transform is defined in [backup_transform.jolt](resources/backup_transform.jolt).
+
+***functional specs***
+
+- An API conforming to the [API specification](resources/api_spec.yaml) is exposed.
+```
+
+## Path Rules
+
+- Paths are resolved **relative to the directory where `turri` is run** (the current working directory).
+- Relative paths may traverse into parent directories — `[resource](../../resources/resource.md)` is valid — as long as they resolve to a real text file on disk.
+- **No external URLs** — only local file references.
+- **No folder paths** — the target must be a file, not a directory.
+- Only text-based files are supported.
+
+### A linked resource MUST be a single, text-based file that exists on disk
+
+A linked resource is **always** a single file that exists on disk at the path you reference, **and** that file's content must be text-based. The renderer reads the linked file's bytes and feeds them into the model alongside the spec; a directory, a remote URL, or a binary blob breaks that contract and is one of the most disruptive mistakes you can make when authoring a `.plain` file — the spec looks valid but the renderer either silently ignores the link, fails to read it, or wastes the model's context window on bytes it cannot interpret.
+
+Three things a linked resource **must not** be:
+
+1. **A folder / directory.** `[integrations](src/integrations/)`, `[schemas](resources/schemas/)`, `[host project](../host_project/)` are all invalid — the renderer cannot ingest a directory. If a whole directory's worth of content is relevant, pick the single most representative **file** inside it (a `README.md`, an exemplar source file, a manifest at the directory root) and link **that**.
+2. **A URL / external location.** `[Stripe docs](https://stripe.com/docs/api)`, `[OpenAPI spec](https://example.com/openapi.json)`, any `http://` / `https://` / `ftp://` / `git://` / `s3://` / `gs://` target. Linked resources are local-file only. If a URL's content is essential to the spec, fetch it once, save the response to a text file under `resources/` (e.g. `resources/stripe-docs-snapshot.md`, `resources/example-openapi.yaml`), and link **that file**.
+3. **A binary file.** PNG, JPG, JPEG, GIF, BMP, TIFF, WebP, ICO, PDF, DOCX, XLSX, PPTX, ZIP, TAR, GZ, MP3, MP4, WAV, compiled binaries (`.exe`, `.so`, `.dylib`, `.class`, `.wasm`), and anything else that isn't human-readable text in its raw form. Binary content cannot be meaningfully consumed by the renderer; linking a screenshot, a PDF spec, or a packaged artifact accomplishes nothing except bloating the context. If the information in a binary asset is essential, transcribe it into a text-based form first — a UI screenshot becomes a Markdown description or a structured YAML wireframe under `resources/`; a PDF spec becomes a Markdown extract or the underlying JSON Schema / OpenAPI; an architecture diagram becomes a Mermaid block inside a Markdown file.
+
+If the markdown-link target ends with `/`, contains `://`, points at a path that resolves to a directory, or points at a file with a binary extension (see the list above), **stop** — it cannot be a linked resource. Convert it to a text file under `resources/` first, then link the converted file.
+
+### Do not mention URLs or folder paths in `.plain` content at all
+
+The constraint above is **not** just about markdown link syntax. URLs (any `http://`, `https://`, `ftp://`, `git://`, `s3://`, … string) and folder paths (`src/integrations/`, `../host_project/`, anything ending with `/`, anything that resolves to a directory) **must not appear anywhere in `.plain` content** — not as link targets, not in concept body prose, not in functional-spec text, not in implementation-reqs. Mentioning a URL or a folder in prose is a critical and common mistake because:
+
+- The renderer cannot follow URLs or open folders. A URL or folder reference in prose is a *ghost* dependency: it looks meaningful to a human reader, but it contributes nothing to code generation. Worse, downstream readers (and future you) assume the renderer used the referenced content, so the spec drifts from reality.
+- The fix is always the same: if external content matters, fetch it (or pick one canonical file out of the directory), save it as a text file under `resources/`, and refer to it through a normal linked resource. The concept or spec then names the content through the linked file, not through a URL or folder path string.
+
+The **only** exceptions are URLs and paths that are *values the produced software itself uses at runtime* (e.g. the base URL the integration calls, a database connection path, a CLI argument value). Those are configuration values, not external references, and they belong in the spec because the generated code needs them. A useful litmus test: "Would the renderer benefit from reading the bytes at this URL / folder?" If yes, save it to a text file and link the file. If no (it's a runtime value), it can stay as plain text in the spec.
+
+### What a linked resource CAN be
+
+- A single file inside the project, reachable by a path relative to where `turri` is run — parent-directory traversal (`../`) is allowed (`resources/` is the conventional home).
+- A **text-based** file the renderer can read end-to-end: JSON, YAML, XML, HTML, Markdown, plain text, CSV, TSV, source code in any language (`.py`, `.js`, `.ts`, `.go`, `.java`, `.rb`, `.rs`, `.kt`, `.swift`, `.c`, `.cpp`, `.cs`, …), shell scripts, SQL, JSON Schema, OpenAPI, AsyncAPI, Protobuf `.proto`, GraphQL SDL, `.jolt`, `.env.example`, `.toml`, `.ini`, `.proto`, `Dockerfile`, etc.
+
+## Common Resource Types
+
+| Type | Typical location | Use case |
+|------|-----------------|----------|
+| JSON Schema | `resources/*.json` | Defining data structure contracts |
+| OpenAPI / Swagger spec | `resources/*.yaml` | API endpoint definitions |
+| Data transforms | `resources/*.jolt` | Data transformation rules |
+| Test fixtures | `resources/*.json`, `resources/*.csv` | Sample data for tests |
+| Configuration examples | `resources/*.yaml` | Reference configurations |
+
+## When to Use Resources
+
+- The information is too detailed or structured to express inline in the spec (e.g., a full JSON schema).
+- The same data is referenced by multiple specs or sections.
+- The resource is an industry-standard format (OpenAPI, JSON Schema) that the renderer can interpret directly.
+
+## When NOT to Use Resources
+
+- The information is short enough to include inline in the spec text.
+- The file is generated code (those belong in `plain_modules/`, not `resources/`).
+
+## Validation Checklist
+
+- [ ] Resource file exists at the specified path
+- [ ] **Target is a file on disk, not a directory** (the path does not end in `/` and does not resolve to a folder)
+- [ ] **Target is a local path, not a URL** (no `://` anywhere in the target: no `http://`, `https://`, `ftp://`, `git://`, `s3://`, `gs://`, etc.)
+- [ ] **Target is a text-based file** (no binary extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.tiff`, `.webp`, `.ico`, `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.zip`, `.tar`, `.gz`, `.mp3`, `.mp4`, `.wav`, `.exe`, `.so`, `.dylib`, `.class`, `.wasm`, …)
+- [ ] **No URLs or folder paths anywhere in the surrounding `.plain` content** (not as link targets, not in body prose), with the sole exception of URLs / paths that are runtime values the generated software itself uses
+- [ ] Path is relative to the `.plain` file, not absolute
+- [ ] Path resolves to a real text file on disk from where `turri` is run (`../` traversal is allowed)
+- [ ] Markdown link syntax is correct: `[display text](relative/path)`
+- [ ] Resource content is relevant and adds value beyond what the spec text says

package/genome/skills/add-template/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: add-template
+description: >-
+  Create or include a Liquid template in a ***plain spec file using
+  {% include %} syntax. Use when the same spec content needs to be reused
+  across multiple .plain files with different parameters.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Add Template
+
+Templates use Liquid syntax (`{% include %}`) to reuse the same spec content across multiple `.plain` files. Each inclusion can pass different parameters, producing tailored output from a single source. This is distinct from `import` and `requires` — templates are about textual reuse with parameterization, not module dependencies.
+
+## When to Use Templates
+
+- The **exact same spec structure** is needed in more than one `.plain` file.
+- The reused content differs only in specific values (names, paths, config) that can be parameterized.
+- You want a single source of truth for a pattern that appears in multiple modules.
+
+## Format
+
+### Including a Template
+
+Use `{% include %}` with the template path and parameters:
+
+```plain
+{% include "console_app_template.plain", main_file_name: "app.py", app_name: "MyApp" %}
+```
+
+Parameters are passed as key-value pairs after the template path. Inside the template, parameters are accessed using Liquid variable syntax (`{{ main_file_name }}`).
+
+### Writing a Template
+
+Templates live in the `template/` directory. Only **variables** (`{{ variable_name }}`) are supported — conditionals, loops, and other Liquid features are not available:
+
+```plain
+***definitions***
+- :{{ app_name }}MainFile: is the entry point file for :{{ app_name }}:.
+
+***implementation reqs***
+- :{{ app_name }}MainFile: should be called "{{ main_file_name }}".
+```
+
+## Workflow: Including an Existing Template
+
+1. **Check the `template/` directory** to see what templates are available.
+2. **Read the template** to understand what parameters it expects and what content it produces.
+3. **Add the `{% include %}` statement** to the target `.plain` file with the correct parameters.
+4. **Verify** that the expanded content does not introduce concept name collisions or duplicate sections.
+
+## Workflow: Creating a New Template
+
+1. **Identify the repeated pattern** — find spec content that is duplicated (or will be duplicated) across multiple `.plain` files.
+2. **Extract the common content** into a new `.plain` file in the `template/` directory.
+3. **Parameterize the differences** — replace the varying parts with Liquid variables.
+4. **Update the original files** to use `{% include %}` instead of the duplicated content.
+
+## Validation Checklist
+
+- [ ] Template file is in the `template/` directory
+- [ ] All varying parts are parameterized with Liquid variables
+- [ ] All required parameters are passed at each `{% include %}` call site
+- [ ] Expanded content does not introduce concept name collisions
+- [ ] Template is used by more than one `.plain` file (otherwise, inline the content)

package/genome/skills/add-test-requirement/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: add-test-requirement
+description: >-
+  Add a test requirement to the ***test reqs*** section of a ***plain spec
+  file. Use when the user wants to specify conformance testing instructions
+  like test frameworks, execution methods, or testing constraints in a .plain
+  file.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Add Test Requirement
+
+## Workflow
+
+1. **Identify the target `.plain` file.** If ambiguous, ask the user.
+2. **Read the file** to understand existing test reqs and the overall spec structure.
+3. **Confirm this is a conformance test concern** — unit test guidance goes in `***implementation reqs***`, not here.
+4. **Draft the requirement** following the rules below.
+5. **Insert it** into the `***test reqs***` section.
+6. **Read the file again** to confirm correct placement and syntax.
+
+## What Belongs Here
+
+Test reqs specify how **conformance tests** should be written and run. Common contents:
+
+- **Test framework**: which framework to use (e.g., pytest, Unittest, xUnit)
+- **Execution method**: the command to run the tests
+- **Testing constraints**: what must or must not be done in tests (e.g., no skipping tests, mock requirements)
+- **Test data**: how test fixtures or mock data should be structured
+- **Environment setup**: any prerequisites for running conformance tests
+
+## What Does NOT Belong Here
+
+- **Unit test guidance** — that goes in `***implementation reqs***`
+- **Acceptance tests** — those are nested under individual functional specs in `***functional specs***`
+- **Behavioral requirements** — those go in `***functional specs***`
+- **Technology choices for the implementation** — those go in `***implementation reqs***`
+
+## Conformance Tests vs Other Tests
+
+| Test Type | Where to Specify | Purpose |
+|-----------|-----------------|---------|
+| Unit tests | `***implementation reqs***` | Test individual functionalities in isolation |
+| Conformance tests | `***test reqs***` | Verify implementation conforms to the full spec |
+| Acceptance tests | `***acceptance tests***` under a functional spec | Verify a specific functional spec |
+
+## Format
+
+Test reqs are bullet points in the `***test reqs***` section:
+
+```plain
+***test reqs***
+
+- :ConformanceTests: should be implemented using pytest framework.
+
+- :ConformanceTests: will be run using "pytest" command.
+
+- :ConformanceTests: must be implemented and executed - do not skip tests.
+
+- :ConformanceTests: should mock all external HTTP calls.
+```
+
+Reference predefined concepts like `:ConformanceTests:` and any defined `:Concepts:` where they add clarity.
+
+
+## Validation Checklist
+
+- [ ] Describes conformance testing concerns, not unit tests or behavior
+- [ ] All referenced `:Concepts:` are defined (or are predefined like `:ConformanceTests:`)
+- [ ] Does not duplicate guidance already present in the file or its imports
+- [ ] Trimmed per `concise-specs.md`: plain words, no rationale, no default framework behavior
+- [ ] Placed inside a `***test reqs***` section
+- [ ] No behavioral requirements that should be in `***functional specs***`

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

@@ -0,0 +1,101 @@
+---
+name: analyze-2-func-specs
+description: >-
+  Analyze two functional specs from a ***plain spec file to determine if they
+  conflict. Use when the user wants to check whether two specific functional
+  requirements are compatible, or when debugging a suspected conflict between
+  two specs.
+allowed-tools: [read, ls, grep, find]
+---
+
+# Analyze Two Functional Specs
+
+## Input
+
+Two functional specs from a `.plain` file (or across `requires` modules). The user provides them directly or points to them by location in a file.
+
+## Workflow
+
+1. **Read both functional specs** and the `***definitions***` section so all referenced `:Concepts:` are understood.
+2. **Determine chronological order** — which spec comes first? The earlier spec was rendered first and the later spec was rendered with the earlier one in context.
+3. **Run the conflict analysis** using the checklist below.
+4. **Output the verdict and nothing else** — either `COMPATIBLE` or `CONFLICTING`. No reasoning, no category labels, no resolution suggestions.
+
+## Conflict Analysis Checklist
+
+Work through each question. If any answer is "yes", the specs likely conflict.
+
+### 1. Direct Contradiction
+
+Do the two 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.
+
+Verdict: CONFLICTING — both define the sort order for the same response,
+but specify different fields and directions. A single implementation cannot
+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?
+
+```
+Spec A: :TaskList: is initially empty.
+Spec B: :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?
+
+```
+Spec A: :User: credentials are validated using an API key.
+Spec B: :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.
+```
+
+### 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?
+
+```
+Spec A: All :Resource: items are returned.
+Spec B: 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).
+```
+
+### 5. Shared Concept, Different Constraints
+
+Do both 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.
+
+Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
+```
+
+## Output Format
+
+The skill emits exactly one of these two strings, with no surrounding text, explanation, category label, or resolution suggestion:
+
+```
+COMPATIBLE
+```
+
+or
+
+```
+CONFLICTING
+```
+
+The internal analysis (checklist, chronological reasoning) informs the verdict but must not appear in the output. The caller decides what to do with the result — typically: act on `COMPATIBLE` by proceeding, or invoke `resolve-spec-conflict` on `CONFLICTING` to produce the actual fix.

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

@@ -0,0 +1,123 @@
+---
+name: analyze-func-specs
+description: >-
+  Analyze a batch of functional specs from a ***plain spec 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).
+allowed-tools: [read, ls, grep, find]
+---
+
+# Analyze Functional Specs
+
+## Input
+
+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.
+
+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.
+
+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.
+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.
+
+## Conflict Analysis Checklist (applied per pair)
+
+Work through each question for the pair under inspection. If any answer is "yes", that pair is CONFLICTING.
+
+### 1. Direct Contradiction
+
+Do the two 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.
+
+Verdict: CONFLICTING — both define the sort order for the same response,
+but specify different fields and directions. A single implementation cannot
+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?
+
+```
+Spec A: :TaskList: is initially empty.
+Spec B: :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?
+
+```
+Spec A: :User: credentials are validated using an API key.
+Spec B: :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.
+```
+
+### 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?
+
+```
+Spec A: All :Resource: items are returned.
+Spec B: 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).
+```
+
+### 5. Shared Concept, Different Constraints
+
+Do both 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.
+
+Verdict: COMPATIBLE — Spec B adds a conditional refinement, not a contradiction.
+```
+
+## Output Format
+
+Emit exactly one of the two shapes below, with no surrounding text, explanation, category label, or resolution suggestion.
+
+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:
+
+```
+CONFLICTING
+S1 x S4
+S2 x S3
+S3 x S5
+```
+
+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).
+
+The internal pairwise analysis informs the verdict but must not appear in the output.