@opengroundplan/core 0.1.1

package/templates/architectures/onion/files/internal/arch/rings_test.go

@@ -0,0 +1,112 @@
+package arch
+
+import (
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// Palermo's rule as a fitness function: all coupling points toward the centre.
+// `go test ./...` fails when a ring imports one further out. Stdlib only, no linter to install.
+func TestCouplingPointsTowardTheCentre(t *testing.T) {
+	root := moduleRoot(t)
+	fileSet := token.NewFileSet()
+
+	err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if entry.IsDir() {
+			if skipDir(entry.Name()) && path != root {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if !strings.HasSuffix(entry.Name(), ".go") {
+			return nil
+		}
+
+		relative, err := filepath.Rel(root, path)
+		if err != nil {
+			return err
+		}
+		relative = filepath.ToSlash(relative)
+
+		from := ringOf(relative)
+		if from < 0 {
+			return nil
+		}
+
+		parsed, err := parser.ParseFile(fileSet, path, nil, parser.ImportsOnly)
+		if err != nil {
+			return err
+		}
+		for _, spec := range parsed.Imports {
+			imported := strings.Trim(spec.Path.Value, `"`)
+			to := ringOfImport(imported)
+			if to > from {
+				t.Errorf("%s (%s) imports %s (%s) — coupling must point toward the centre",
+					relative, Rings[from], imported, Rings[to])
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("walking %s: %v", root, err)
+	}
+}
+
+// Guards the layout itself: a renamed or deleted ring would make the walk above vacuous.
+func TestEveryRingDirectoryExists(t *testing.T) {
+	root := moduleRoot(t)
+	for _, ring := range Rings {
+		if _, err := os.Stat(filepath.Join(root, filepath.FromSlash(ring))); err != nil {
+			t.Errorf("ring %s is missing: %v", ring, err)
+		}
+	}
+}
+
+func ringOf(relative string) int {
+	for i, ring := range Rings {
+		if strings.HasPrefix(relative, ring+"/") {
+			return i
+		}
+	}
+	return -1
+}
+
+// Matches on the module-relative suffix so the module path never has to be hardcoded.
+func ringOfImport(imported string) int {
+	for i, ring := range Rings {
+		if imported == ring || strings.HasSuffix(imported, "/"+ring) {
+			return i
+		}
+	}
+	return -1
+}
+
+func skipDir(name string) bool {
+	return name == "vendor" || name == "testdata" || (strings.HasPrefix(name, ".") && name != ".")
+}
+
+func moduleRoot(t *testing.T) string {
+	t.Helper()
+	dir, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	for {
+		if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
+			return dir
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			t.Fatal("no go.mod found above the test's working directory")
+		}
+		dir = parent
+	}
+}

package/templates/architectures/onion/files/internal/domain/doc.go

@@ -0,0 +1,4 @@
+// Package domain is ring 1 — the Domain Model: entities, value objects, domain events.
+//
+// It imports no other ring and no database driver. The Domain Model is coupled only to itself.
+package domain

package/templates/architectures/onion/files/internal/domainservices/doc.go

@@ -0,0 +1,5 @@
+// Package domainservices is ring 2 — behaviour spanning entities, plus repository interfaces.
+//
+// Palermo puts repository interfaces in the first ring around the Domain Model; the
+// implementations that talk to a database live in internal/infrastructure.
+package domainservices

package/templates/architectures/onion/files/internal/infrastructure/doc.go

@@ -0,0 +1,5 @@
+// Package infrastructure is the outer edge — repository implementations, clients, adapters.
+//
+// Every type here satisfies an interface declared in a ring further in. Nothing inner
+// imports this package; cmd/ wires the concrete types in at startup.
+package infrastructure

package/templates/architectures/onion/files/pyproject.toml

@@ -0,0 +1,2 @@
+[dependency-groups]
+dev = ["import-linter==2.13"]

package/templates/architectures/onion/files/src/__solutionName.dot__.ApplicationServices/ApplicationServicesAssemblyMarker.cs

@@ -0,0 +1,4 @@
+namespace {{ solutionName | dot }}.ApplicationServices;
+
+// Anchor for assembly scanning and the ring fitness tests while this ring holds no types yet.
+public sealed class ApplicationServicesAssemblyMarker;

package/templates/architectures/onion/files/src/__solutionName.dot__.ApplicationServices/__solutionName.dot__.ApplicationServices.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <RootNamespace>{{ solutionName | dot }}.ApplicationServices</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.ApplicationServices</AssemblyName>
+  </PropertyGroup>
+
+  <!-- Ring 3. Reaches the Domain Model transitively; never references Infrastructure. -->
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | dot }}.DomainServices/{{ solutionName | dot }}.DomainServices.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/onion/files/src/__solutionName.dot__.Domain/DomainAssemblyMarker.cs

@@ -0,0 +1,4 @@
+namespace {{ solutionName | dot }}.Domain;
+
+// Anchor for assembly scanning and the ring fitness tests while this ring holds no types yet.
+public sealed class DomainAssemblyMarker;

package/templates/architectures/onion/files/src/__solutionName.dot__.Domain/__solutionName.dot__.Domain.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <RootNamespace>{{ solutionName | dot }}.Domain</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Domain</AssemblyName>
+  </PropertyGroup>
+
+  <!-- Ring 1, the centre. No ProjectReference and no PackageReference belongs here: the
+       Domain Model is coupled only to itself. -->
+
+</Project>

package/templates/architectures/onion/files/src/__solutionName.dot__.DomainServices/DomainServicesAssemblyMarker.cs

@@ -0,0 +1,4 @@
+namespace {{ solutionName | dot }}.DomainServices;
+
+// Anchor for assembly scanning and the ring fitness tests while this ring holds no types yet.
+public sealed class DomainServicesAssemblyMarker;

package/templates/architectures/onion/files/src/__solutionName.dot__.DomainServices/Repositories/.gitkeep

@@ -0,0 +1,2 @@
+# Repository *interfaces* only. Palermo puts them in the first ring around the Domain Model;
+# the implementations live on the outer edge, in the Infrastructure project.

package/templates/architectures/onion/files/src/__solutionName.dot__.DomainServices/__solutionName.dot__.DomainServices.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <RootNamespace>{{ solutionName | dot }}.DomainServices</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.DomainServices</AssemblyName>
+  </PropertyGroup>
+
+  <!-- Ring 2. Inward only — adding a reference to a ring further out closes a cycle and
+       MSBuild refuses to restore. -->
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | dot }}.Domain/{{ solutionName | dot }}.Domain.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/onion/files/src/__solutionName.dot__.Infrastructure/InfrastructureAssemblyMarker.cs

@@ -0,0 +1,4 @@
+namespace {{ solutionName | dot }}.Infrastructure;
+
+// Anchor for assembly scanning and the ring fitness tests while this ring holds no types yet.
+public sealed class InfrastructureAssemblyMarker;

package/templates/architectures/onion/files/src/__solutionName.dot__.Infrastructure/Repositories/.gitkeep

@@ -0,0 +1,2 @@
+# Repository implementations. Each one implements an interface declared in the
+# DomainServices project — that inversion is what keeps the database outside the core.

package/templates/architectures/onion/files/src/__solutionName.dot__.Infrastructure/__solutionName.dot__.Infrastructure.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <RootNamespace>{{ solutionName | dot }}.Infrastructure</RootNamespace>
+    <AssemblyName>{{ solutionName | dot }}.Infrastructure</AssemblyName>
+  </PropertyGroup>
+
+  <!-- Outer edge. Persistence, HTTP clients, and the framework packages they need go here so
+       the inner rings never acquire them. -->
+  <ItemGroup>
+    <ProjectReference Include="../{{ solutionName | dot }}.ApplicationServices/{{ solutionName | dot }}.ApplicationServices.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/onion/files/src/__solutionName.snake__/application_services/__init__.py

@@ -0,0 +1,4 @@
+"""Ring 3 — Application Services. Use-case orchestration, one module per use case.
+
+May import `domain_services` and `domain`. Never imports `infrastructure` or `api`.
+"""

package/templates/architectures/onion/files/src/__solutionName.snake__/domain/__init__.py

@@ -0,0 +1,5 @@
+"""Ring 1 — Domain Model. Entities, value objects, domain events.
+
+Imports nothing from this package's other rings and nothing from a persistence library:
+the Domain Model is coupled only to itself.
+"""

package/templates/architectures/onion/files/src/__solutionName.snake__/domain_services/__init__.py

@@ -0,0 +1,6 @@
+"""Ring 2 — Domain Services. Behaviour that spans entities, plus repository *interfaces*.
+
+Palermo puts repository interfaces in the first ring around the Domain Model; the
+implementations that touch a database live on the outer edge, in `infrastructure`.
+May import `domain` only.
+"""

package/templates/architectures/onion/files/src/__solutionName.snake__/infrastructure/__init__.py

@@ -0,0 +1,5 @@
+"""Outer edge — Infrastructure. Repository implementations, HTTP clients, message buses.
+
+Every class here implements an interface declared in a ring further in. May import any
+inner ring; nothing inner may import this package.
+"""

package/templates/architectures/onion/files/src/application-services/index.ts

@@ -0,0 +1,3 @@
+// Ring 3 — Application Services. One module per use case, orchestrating the inner rings.
+// May reach src/domain-services and src/domain. Never src/infrastructure.
+export {};

package/templates/architectures/onion/files/src/domain/index.ts

@@ -0,0 +1,3 @@
+// Ring 1 — Domain Model. Entities, value objects, domain events.
+// Imports nothing from src/ outside this folder: the Domain Model is coupled only to itself.
+export {};

package/templates/architectures/onion/files/src/domain-services/index.ts

@@ -0,0 +1,3 @@
+// Ring 2 — Domain Services. Behaviour spanning entities, plus repository *interfaces*.
+// Palermo puts repository interfaces here; their implementations live in src/infrastructure.
+export {};

package/templates/architectures/onion/files/src/infrastructure/index.ts

@@ -0,0 +1,3 @@
+// Outer edge — Infrastructure. Repository implementations, HTTP clients, message buses.
+// Each implements an interface declared in a ring further in; nothing inner imports this.
+export {};

package/templates/architectures/onion/files/tests/__solutionName.dot__.ArchitectureTests/RingDependencyTests.cs

@@ -0,0 +1,104 @@
+using ArchUnitNET.Domain;
+using ArchUnitNET.Fluent;
+using ArchUnitNET.Loader;
+using Xunit;
+using {{ solutionName | dot }}.ApplicationServices;
+using {{ solutionName | dot }}.Domain;
+using {{ solutionName | dot }}.DomainServices;
+using {{ solutionName | dot }}.Infrastructure;
+using static ArchUnitNET.Fluent.ArchRuleDefinition;
+
+namespace {{ solutionName | dot }}.ArchitectureTests;
+
+/// Palermo's rule as a fitness function: all coupling points toward the centre.
+public sealed class RingDependencyTests
+{
+    private const string DomainModelRing = "{{ solutionName | dot }}.Domain";
+    private const string DomainServicesRing = "{{ solutionName | dot }}.DomainServices";
+    private const string ApplicationServicesRing = "{{ solutionName | dot }}.ApplicationServices";
+    private const string OuterEdgeRing = "{{ solutionName | dot }}.Infrastructure";
+
+    private static readonly Architecture Rings = new ArchLoader()
+        .LoadAssemblies(
+            typeof(DomainAssemblyMarker).Assembly,
+            typeof(DomainServicesAssemblyMarker).Assembly,
+            typeof(ApplicationServicesAssemblyMarker).Assembly,
+            typeof(InfrastructureAssemblyMarker).Assembly)
+        .Build();
+
+    private static IObjectProvider<IType> Ring(string assembly) =>
+        Types().That().ResideInAssembly(assembly).As(assembly);
+
+    /// Guards the rename: a stale assembly name would make every rule below pass vacuously.
+    [Fact]
+    public void Every_ring_assembly_is_loaded()
+    {
+        string[] expected = [DomainModelRing, DomainServicesRing, ApplicationServicesRing, OuterEdgeRing];
+        var loaded = Rings.Assemblies.Select(assembly => assembly.Name).ToList();
+        Assert.All(expected, name => Assert.Contains(name, loaded));
+    }
+
+    [Fact]
+    public void Domain_model_is_coupled_only_to_itself()
+    {
+        Check(Types().That().Are(Ring(DomainModelRing)).Should()
+            .NotDependOnAny(Ring(DomainServicesRing)).AndShould()
+            .NotDependOnAny(Ring(ApplicationServicesRing)).AndShould()
+            .NotDependOnAny(Ring(OuterEdgeRing))
+            .WithoutRequiringPositiveResults());
+    }
+
+    [Fact]
+    public void Domain_services_do_not_depend_further_out()
+    {
+        Check(Types().That().Are(Ring(DomainServicesRing)).Should()
+            .NotDependOnAny(Ring(ApplicationServicesRing)).AndShould()
+            .NotDependOnAny(Ring(OuterEdgeRing))
+            .WithoutRequiringPositiveResults());
+    }
+
+    [Fact]
+    public void Application_services_do_not_depend_on_the_outer_edge()
+    {
+        Check(Types().That().Are(Ring(ApplicationServicesRing)).Should()
+            .NotDependOnAny(Ring(OuterEdgeRing))
+            .WithoutRequiringPositiveResults());
+    }
+
+    /// The compiler cannot see this one: a repository interface declared in the wrong ring
+    /// still compiles. Palermo puts it in the first ring around the Domain Model.
+    [Fact]
+    public void Repository_interfaces_live_in_the_domain_services_ring()
+    {
+        Check(Interfaces().That().HaveNameEndingWith("Repository").Should()
+            .ResideInAssembly(DomainServicesRing)
+            .WithoutRequiringPositiveResults());
+    }
+
+    [Fact]
+    public void Repository_implementations_live_on_the_outer_edge()
+    {
+        Check(Classes().That().HaveNameEndingWith("Repository").Should()
+            .ResideInAssembly(OuterEdgeRing)
+            .WithoutRequiringPositiveResults());
+    }
+
+    /// The headline Onion claim — the database is external, so the centre never names it.
+    [Fact]
+    public void Domain_model_knows_nothing_about_persistence()
+    {
+        Check(Types().That().Are(Ring(DomainModelRing)).Should()
+            .NotDependOnAnyTypesThat()
+            .ResideInNamespaceMatching(@"^(Microsoft\.EntityFrameworkCore|System\.Data)($|\.)")
+            .WithoutRequiringPositiveResults());
+    }
+
+    private static void Check(IArchRule rule)
+    {
+        var violations = rule.Evaluate(Rings)
+            .Where(result => !result.Passed)
+            .Select(result => result.Description)
+            .ToList();
+        Assert.True(violations.Count == 0, string.Join(Environment.NewLine, violations));
+    }
+}

package/templates/architectures/onion/files/tests/__solutionName.dot__.ArchitectureTests/__solutionName.dot__.ArchitectureTests.csproj

@@ -0,0 +1,31 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <!-- xUnit v3 test projects are executables. -->
+    <OutputType>Exe</OutputType>
+    <RootNamespace>{{ solutionName | dot }}.ArchitectureTests</RootNamespace>
+    <IsPackable>false</IsPackable>
+    <IsTestProject>true</IsTestProject>
+    <!-- CA1707: underscored test names are the convention here. CA1859: the fluent rules are
+         held as IArchRule on purpose; the concrete conjunction type is an implementation
+         detail of ArchUnitNET. -->
+    <NoWarn>$(NoWarn);CA1707;CA1859</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- ArchUnitNET core only. TngTech.ArchUnitNET.xUnit still pins xunit.assert 2.x, which
+         collides with xunit.v3's Assert; the Check helper below replaces its one extension. -->
+    <PackageReference Include="TngTech.ArchUnitNET" />
+    <PackageReference Include="xunit.v3" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Domain/{{ solutionName | dot }}.Domain.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.DomainServices/{{ solutionName | dot }}.DomainServices.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.ApplicationServices/{{ solutionName | dot }}.ApplicationServices.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Infrastructure/{{ solutionName | dot }}.Infrastructure.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/pipes-and-filters/blueprint.yaml

@@ -0,0 +1,104 @@
+id: pipes-and-filters
+kind: architecture
+name: Pipes and Filters
+description: >-
+  Folder overlay that splits processing into independent, stateless stages behind one uniform
+  interface, connected by an explicit pipeline definition that owns the order. Ships a shared
+  stage contract, one worked stage with its own test, and a boundary check per stack that fails
+  when a stage imports a sibling stage or the pipeline definition.
+
+tags:
+  - pipes-and-filters
+  - pipeline
+  - stages
+  - filters
+  - boundaries
+  - import-linter
+
+requires: []
+conflicts: []
+provides:
+  - pipeline-layout
+  - stage-contract
+  - boundary-enforcement
+
+# An overlay is chosen through the architecture question, never listed as a supported target.
+supportsArchitectures: []
+
+variables:
+  # Filters are the unit of work here, so the layout means nothing without one to copy.
+  - name: firstStage
+    prompt: Name of the first pipeline stage (one folder is created for it)
+    type: string
+    default: normalize
+    required: false
+
+  # Go import paths are absolute, so the pipeline definition needs the module path at
+  # generation time. Matches the go-api base's default so the two agree when both are used.
+  - name: moduleHost
+    prompt: Go module path prefix (VCS host and org, without the repo name)
+    type: string
+    default: github.com/example
+    required: false
+    when: "stack == 'go'"
+
+files:
+  # ── docs ────────────────────────────────────────────────────────────────────
+  # One doc per layout, not per stack id: TypeScript and Node share a single tree.
+  - from: files/docs/architecture/pipes-and-filters.node.md
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/docs/architecture/pipes-and-filters.python.md
+    to: .
+    when: "stack == 'python'"
+  - from: files/docs/architecture/pipes-and-filters.go.md
+    to: .
+    when: "stack == 'go'"
+
+  # ── typescript / node ───────────────────────────────────────────────────────
+  - from: files/src/pipeline/contract.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/pipeline/config.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/pipeline/pipeline.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/pipeline/stages/__firstStage.kebab__/**
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  # A boundary rule that lives only in prose gets violated; this exits non-zero instead.
+  - from: files/scripts/check-stage-boundaries.mjs
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  # The stage test imports vitest, so this overlay must be the one that declares it.
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - from: files/src/__solutionName.snake__/pipeline/**
+    to: .
+    when: "stack == 'python'"
+  - from: files/tests/pipeline/*.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/tests/architecture/test_stage_boundaries.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+  # Declared, not installed by a post-apply step: a package added after generation is missing
+  # from the first install (ADR 0005, spec 003). The pytest fitness test needs nothing.
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+  # ── go ──────────────────────────────────────────────────────────────────────
+  - from: files/internal/pipeline/**
+    to: .
+    when: "stack == 'go'"

package/templates/architectures/pipes-and-filters/files/.importlinter

@@ -0,0 +1,25 @@
+# import-linter contracts — the standard-tool half of the boundary enforcement.
+# `lint-imports` fails the build; wire it into CI next to pytest and ruff.
+# The full "a stage may import only the contract" rule is enforced by
+# tests/architecture/test_stage_boundaries.py, which needs no per-stage upkeep.
+[importlinter]
+root_package = {{ solutionName | snake }}
+
+# As you add stages, list them here so import-linter proves they never couple to each other.
+# Independence forbids imports in BOTH directions between every pair named.
+[importlinter:contract:stages-are-independent]
+name = Filters do not import one another
+type = independence
+modules =
+    {{ solutionName | snake }}.pipeline.stages.{{ firstStage | snake }}
+
+# The pipeline knows its stages; a stage must never know the pipeline, or the order stops
+# being a property of one file.
+[importlinter:contract:stages-depend-only-on-the-contract]
+name = A stage may not import the pipeline definition or its config
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.pipeline.stages
+forbidden_modules =
+    {{ solutionName | snake }}.pipeline.pipeline
+    {{ solutionName | snake }}.pipeline.config

package/templates/architectures/pipes-and-filters/files/docs/architecture/pipes-and-filters.go.md

@@ -0,0 +1,72 @@
+# Architecture — Pipes and Filters (Go)
+
+Processing is split into independent stages behind one uniform interface. A pipe connects two
+stages and carries nothing but a message; a pipe never routes and never decides.
+
+## The one rule that matters
+
+> **A stage may import `internal/pipeline/contract` and nothing else from the pipeline.** Not a
+> sibling stage, not the `pipeline` package itself. `go test ./internal/pipeline` fails the
+> build the moment one does.
+
+Break it and the stages stop being reorderable, which is the only reason to pay for this
+architecture at all.
+
+## Layout
+
+```
+internal/pipeline/
+  contract/
+    contract.go                    # Message, Stage, Forward — the shared contract
+  config.go                        # every tunable and its default, read once at the composition root
+  pipeline.go                      # THE pipeline definition: Stages() order + Run
+  boundary_test.go                 # the fitness test
+  stages/
+    {{ firstStage | lower }}/
+      {{ firstStage | lower }}.go        # one filter; imports contract only
+      {{ firstStage | lower }}_test.go   # its own test, no pipeline involved
+```
+
+Add a stage by copying `stages/{{ firstStage | lower }}/` and adding it to `Stages()` in
+`pipeline.go`. Registration lives in exactly one file so reordering is a one-line diff.
+
+## Wiring it up
+
+```go
+cfg := pipeline.DefaultConfig()
+out, err := pipeline.Run(ctx, cfg, contract.Message{ID: jobID, Attempt: 1, Payload: payload})
+```
+
+`PIPELINE_STAGE_TIMEOUT` (a Go duration, e.g. `45s`) and `PIPELINE_MAX_ATTEMPTS` are the only
+knobs, and `config.go` is the only place their defaults exist.
+
+## Enforcement
+
+| Guard | Command | What fails it |
+|---|---|---|
+| Stage boundary fitness test | `go test ./internal/pipeline` | a stage importing a sibling stage or the `pipeline` package |
+| Rule self-test | same run, `TestTheRuleStillDetectsAViolation` | the rule itself silently stopping to fire |
+| Per-stage tests | `go test ./...` | a stage that is not idempotent or drops payload keys |
+
+The fitness test parses imports under `stages/`, so new stages are covered with no upkeep. It is
+worth knowing that Go's own `internal/` rule already blocks a stage from reaching into another
+stage's `internal/` subtree — this test covers the rest of the boundary, which the compiler does
+not see.
+
+## What is *not* enforced mechanically — read this part
+
+The fitness test is a static import check. It cannot see:
+
+- **Statelessness.** A stage holding package-level mutable state passes every check and breaks
+  the first time you run two goroutines. Review for it.
+- **Idempotency.** Microsoft names this non-negotiable: a stage that crashes after doing work
+  but before acknowledging *will* be re-run. Only a test can assert it — the shipped stage test
+  has a `TestIsIdempotent` case; keep one in every stage you add.
+- **Duplicate detection at the pipe.** Redelivery is a property of your queue, not of this
+  layout. Broker-side dedupe or an explicit seen-ids store is your job.
+- **Schema compatibility between neighbours.** `Stages()` returns `[]contract.Stage`, and
+  `Payload` is a `map[string]any`; reordering two incompatible stages compiles fine. Assert it
+  in an integration test over the real order.
+
+Sources: [Pipes and Filters pattern — Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/patterns/pipes-and-filters) ·
+[Azure-Samples/cloud-design-patterns](https://github.com/Azure-Samples/cloud-design-patterns/tree/main/pipes-and-filters).