@opengroundplan/core 0.1.1

package/templates/architectures/modular-monolith/files/tests/__solutionName.dot__.ArchitectureTests/ModuleBoundaryTests.cs

@@ -0,0 +1,102 @@
+using System.Reflection;
+using NetArchTest.Rules;
+using Xunit;
+
+// xUnit ships a TestResult of its own.
+using TestResult = NetArchTest.Rules.TestResult;
+using {{ solutionName | dot }}.SharedKernel.Events;
+
+namespace {{ solutionName | dot }}.ArchitectureTests;
+
+/// <summary>
+/// Fitness functions for the modular monolith. These fail the build, which is the only reason
+/// the boundaries survive contact with a deadline.
+/// </summary>
+public sealed class ModuleBoundaryTests
+{
+    private const string ModulesNamespace = "{{ solutionName | dot }}.Modules";
+    private const string InternalSuffix = ".Internal";
+
+    private static readonly List<Assembly> Modules = LoadModuleAssemblies();
+
+    [Fact]
+    public void Module_assemblies_are_discovered()
+    {
+        // Without this, every rule below would pass by inspecting nothing.
+        Assert.True(
+            Modules.Count > 0,
+            $"No {ModulesNamespace}.*.dll beside the tests, so every rule below would pass by "
+                + "inspecting nothing. Each module needs a ProjectReference in this test "
+                + "project — MSBuild skips a reference whose path is wrong without warning.");
+    }
+
+    [Fact]
+    public void Internal_types_are_never_public()
+    {
+        foreach (var module in Modules)
+        {
+            var result = Types.InAssembly(module)
+                .That().ResideInNamespaceContaining(InternalSuffix)
+                .Should().NotBePublic()
+                .GetResult();
+
+            Assert.True(
+                result.IsSuccessful,
+                Describe($"{module.GetName().Name}: internal implementation leaked as public ", result));
+        }
+    }
+
+    [Fact]
+    public void No_module_reaches_into_another_modules_internals()
+    {
+        foreach (var module in Modules)
+        {
+            var foreign = Modules
+                .Where(other => other != module)
+                .Select(other => other.GetName().Name + InternalSuffix)
+                .ToArray();
+
+            if (foreign.Length == 0)
+            {
+                continue;
+            }
+
+            var result = Types.InAssembly(module)
+                .ShouldNot().HaveDependencyOnAny(foreign)
+                .GetResult();
+
+            Assert.True(
+                result.IsSuccessful,
+                Describe($"{module.GetName().Name} depends on another module's internals ", result));
+        }
+    }
+
+    [Fact]
+    public void Shared_kernel_does_not_depend_on_any_module()
+    {
+        var result = Types.InAssembly(typeof(IEventBus).Assembly)
+            .ShouldNot().HaveDependencyOnAny(ModulesNamespace)
+            .GetResult();
+
+        Assert.True(
+            result.IsSuccessful,
+            Describe("The shared kernel must stay below the modules ", result));
+    }
+
+    /// <summary>Every module assembly a ProjectReference dropped into the test output.</summary>
+    private static List<Assembly> LoadModuleAssemblies()
+    {
+        var directory = Path.GetDirectoryName(typeof(ModuleBoundaryTests).Assembly.Location)!;
+        return Directory.EnumerateFiles(directory, ModulesNamespace + ".*.dll")
+            .Select(Assembly.LoadFrom)
+            .ToList();
+    }
+
+    private static string Describe(string violation, TestResult result)
+    {
+        // FailingTypes is null on a passing test, and this message is built either way.
+        var failing = result.FailingTypes ?? [];
+        var lines = failing.Select(type => $"  {type.FullName} — {type.Explanation}");
+        return string.Join(Environment.NewLine, lines.Prepend(violation));
+    }
+}

package/templates/architectures/modular-monolith/files/tests/__solutionName.dot__.ArchitectureTests/__solutionName.dot__.ArchitectureTests.csproj

@@ -0,0 +1,30 @@
+<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>
+    <!-- Underscored test names are the convention here and the repo builds warnings-as-errors. -->
+    <NoWarn>$(NoWarn);CA1707</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- The maintained fork; NetArchTest.Rules stopped at 1.3.2 in 2021. Same namespace. -->
+    <PackageReference Include="NetArchTest.eNhancedEdition" />
+    <PackageReference Include="xunit.v3" />
+    <PackageReference Include="xunit.runner.visualstudio" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+  </ItemGroup>
+
+  <!-- One line per module. Without a reference the module's assembly never reaches the test
+       output directory, and the boundary rules would pass by finding nothing. MSBuild skips a
+       reference whose file is missing without warning, so `Module_assemblies_are_discovered`
+       is what actually catches a wrong path here. -->
+  <ItemGroup>
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.SharedKernel/{{ solutionName | dot }}.SharedKernel.csproj" />
+    <ProjectReference Include="../../src/{{ solutionName | dot }}.Modules.{{ moduleName | pascal }}/{{ solutionName | dot }}.Modules.{{ moduleName | pascal }}.csproj" />
+  </ItemGroup>
+
+</Project>

package/templates/architectures/modular-monolith/files/tests/architecture/test_module_boundaries.py

@@ -0,0 +1,114 @@
+"""Architecture fitness test for the modular monolith.
+
+One rule: from outside a module, the only importable sub-package is that module's `api`.
+Runs under pytest, and standalone (`python tests/architecture/test_module_boundaries.py`) so a
+repo without the test layer still has the guard.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import sys
+from pathlib import Path
+
+# Every tunable lives here; nothing below reads the environment directly.
+CONFIG = {
+    "source_root": Path(os.environ.get("ARCH_SOURCE_ROOT", "src")),
+    "modules_package": os.environ.get("ARCH_MODULES_PACKAGE", "modules"),
+    "shared_package": os.environ.get("ARCH_SHARED_PACKAGE", "shared"),
+    "api_package": "api",
+}
+
+
+def _module_of(dotted: str) -> str | None:
+    """`acme.modules.catalog.internal.service` -> `acme.modules.catalog`."""
+    parts = dotted.split(".")
+    marker = CONFIG["modules_package"]
+    if marker not in parts:
+        return None
+    index = parts.index(marker)
+    return ".".join(parts[: index + 2]) if len(parts) > index + 1 else None
+
+
+def violation(importer: str, imported: str) -> str | None:
+    """The single rule, isolated so the self-test below can prove it still fires."""
+    target = _module_of(imported)
+    if target is None:
+        return None
+
+    shared_prefix = f".{CONFIG['shared_package']}."
+    if shared_prefix in f".{importer}.":
+        return f"{importer} imports {imported}: shared code must stay below the modules"
+
+    if _module_of(importer) == target:
+        return None
+
+    surface = imported[len(target) :].lstrip(".").split(".")
+    if surface == [""] or surface[0] == CONFIG["api_package"]:
+        return None
+    return f"{importer} imports {imported}: {target}.{surface[0]} is private, go through {target}.api"
+
+
+def _dotted_name(path: Path, root: Path) -> str:
+    relative = path.relative_to(root).with_suffix("")
+    parts = list(relative.parts)
+    if parts[-1] == "__init__":
+        parts.pop()
+    return ".".join(parts)
+
+
+def _imports(source: str, importer: str) -> list[str]:
+    found: list[str] = []
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.Import):
+            found.extend(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            base = node.module or ""
+            if node.level:
+                package = importer.split(".")[: -node.level] or [""]
+                base = ".".join([*package, base]) if base else ".".join(package)
+            found.extend(f"{base}.{alias.name}" if base else alias.name for alias in node.names)
+            found.append(base)
+    return [name for name in found if name]
+
+
+def collect_violations(root: Path) -> list[str]:
+    return [
+        message
+        for path in sorted(root.rglob("*.py"))
+        for message in [
+            violation(_dotted_name(path, root), imported)
+            for imported in _imports(path.read_text(encoding="utf-8"), _dotted_name(path, root))
+        ]
+        if message
+    ]
+
+
+SELF_TEST_CASES = [
+    ("acme.modules.orders.internal.x", "acme.modules.catalog.internal.service", True),
+    ("acme.modules.orders.internal.x", "acme.modules.catalog.api.contracts", False),
+    ("acme.modules.catalog.api.factory", "acme.modules.catalog.internal.service", False),
+    ("acme.shared.events.bus", "acme.modules.catalog.api", True),
+    ("acme.main", "acme.modules.catalog.api", False),
+]
+
+
+def test_the_rule_still_detects_a_violation() -> None:
+    for importer, imported, expected in SELF_TEST_CASES:
+        assert bool(violation(importer, imported)) is expected, f"{importer} -> {imported}"
+
+
+def test_no_module_reaches_past_another_modules_api() -> None:
+    root = CONFIG["source_root"]
+    assert root.is_dir(), f"{root} not found — set ARCH_SOURCE_ROOT"
+    found = collect_violations(root)
+    assert not found, "Module boundary violations:\n" + "\n".join(found)
+
+
+if __name__ == "__main__":
+    test_the_rule_still_detects_a_violation()
+    problems = collect_violations(CONFIG["source_root"])
+    for problem in problems:
+        print(problem, file=sys.stderr)
+    sys.exit(1 if problems else 0)

package/templates/architectures/monolith/blueprint.yaml

@@ -0,0 +1,141 @@
+id: monolith
+kind: architecture
+name: Monolith (Single Deployable)
+description: >-
+  The start-here layout: one deployable partitioned into feature folders over a deliberately
+  small shared kernel. Cross-feature calls are allowed, but only through a feature's front
+  door, and the kernel may never name a feature — the two facts that keep extraction possible
+  later. A boundary check per stack fails the build when either is broken.
+
+tags:
+  - monolith
+  - single-deployable
+  - features
+  - shared-kernel
+  - boundaries
+  - netarchtest
+  - import-linter
+
+requires: []
+conflicts: []
+provides:
+  - feature-layout
+  - boundary-enforcement
+
+# An overlay is chosen through the architecture question, never listed as a supported target.
+supportsArchitectures: []
+
+variables:
+  # Features are the unit of work here, so the layout says nothing without one to show the shape.
+  - name: featureName
+    prompt: Name of the first feature (one folder is created for it)
+    type: string
+    default: example
+    required: false
+
+  # Go import paths are absolute, so the module path must be known at generation time.
+  # Same name and default as the go-api base, so a Go interview asks this once.
+  - name: moduleHost
+    prompt: Go module path prefix (VCS host and org, without the repo name)
+    type: string
+    default: github.com/example
+    when: "stack == 'go'"
+
+  - name: netArchTestVersion
+    prompt: NetArchTest.eNhancedEdition version (enforces the feature boundaries in tests)
+    type: string
+    default: '1.4.5'
+    when: "stack == 'dotnet'"
+
+files:
+  # ── docs ────────────────────────────────────────────────────────────────────
+  - from: files/docs/architecture/monolith.node.md
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/docs/architecture/monolith.python.md
+    to: .
+    when: "stack == 'python'"
+  - from: files/docs/architecture/monolith.dotnet.md
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/docs/architecture/monolith.go.md
+    to: .
+    when: "stack == 'go'"
+
+  # ── typescript / node ───────────────────────────────────────────────────────
+  # One layout serves every single-package TS base — Hono, Nest, Next — because the feature root
+  # is the same in all of them. The checker's roots are env-overridable for a restructured repo.
+  - from: files/src/features/**/*.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/shared/*.ts
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/scripts/check-monolith-boundaries.mjs
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - from: files/src/__solutionName.snake__/**/*.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+  - from: files/tests/architecture/test_monolith_boundaries.py
+    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).
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+  # ── dotnet ──────────────────────────────────────────────────────────────────
+  # The two .NET bases name their API project differently — dotnet-webapi uses the `dot`
+  # filter, dotnet-aspire uses `pascal` — and nothing in the variable set identifies the base.
+  # `aspireVersion` is declared only by dotnet-aspire, so it is the available signal; an unknown
+  # name evaluates to undefined, which is falsy, so the webapi branch is the default.
+  - from: files/src/__solutionName.dot__.Api/**/*.cs
+    to: .
+    when: "stack == 'dotnet' && !aspireVersion"
+  - from: files/src/__solutionName.pascal__.Api/**/*.cs
+    to: .
+    when: "stack == 'dotnet' && aspireVersion"
+
+  # Fixed folder name so it never collides with the testing-unit layer's .Tests project, and so
+  # the postApply below can name it — `dotnet sln add` expands no globs and searches no subtree.
+  - from: files/tests/ArchitectureTests/*
+    to: .
+    when: "stack == 'dotnet'"
+
+  # ── go ──────────────────────────────────────────────────────────────────────
+  - from: files/internal/**/*.go
+    to: .
+    when: "stack == 'go'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+  # Central package management: versions live in Directory.Packages.props and projects
+  # reference without one. A bare Version= on a PackageReference fails restore (NU1008).
+  - from: files/Directory.Packages.props
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply:
+  # The csproj pins its own package versions; this only joins it to the solution so that a
+  # plain `dotnet test` runs the boundary check.
+
+  # Manifest-only, matching the other blueprints: no install runs here.
+  - run: npm pkg set "scripts.check:boundaries"="node scripts/check-monolith-boundaries.mjs"
+    when: "stack == 'typescript' || stack == 'node'"
+    optional: true

package/templates/architectures/monolith/files/.importlinter

@@ -0,0 +1,14 @@
+# 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 "enter a feature through its front door" rule is enforced by
+# tests/architecture/test_monolith_boundaries.py, which needs no per-feature upkeep.
+[importlinter]
+root_package = {{ solutionName | snake }}
+
+[importlinter:contract:kernel-below-features]
+name = Shared kernel must not depend on any feature
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.shared
+forbidden_modules =
+    {{ solutionName | snake }}.features

package/templates/architectures/monolith/files/Directory.Packages.props

@@ -0,0 +1,8 @@
+<Project>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.8.1" />
+    <PackageVersion Include="NetArchTest.eNhancedEdition" Version="{{ netArchTestVersion }}" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
+    <PackageVersion Include="xunit.v3" Version="3.2.2" />
+  </ItemGroup>
+</Project>

package/templates/architectures/monolith/files/__solutionName.dot__.slnx

@@ -0,0 +1,5 @@
+<Solution>
+  <Folder Name="/tests/">
+    <Project Path="tests/ArchitectureTests/ArchitectureTests.csproj" />
+  </Folder>
+</Solution>

package/templates/architectures/monolith/files/docs/architecture/monolith.dotnet.md

@@ -0,0 +1,78 @@
+# Architecture — Monolith (single deployable)
+
+One process, one release train, partitioned into features over a deliberately small shared
+kernel. This is the start-here layout: cheap enough that a small team is not paying for
+boundaries it does not need yet, seamed so a feature can be lifted out later.
+
+## The one rule that matters
+
+> **A feature is entered through its front door, and the kernel never walks through it.**
+>
+> From outside `…Api.Features.<Name>`, the only reachable types are the ones in that namespace.
+> `…Api.Features.<Name>.Internal` is private, and `…Api.Kernel` may not depend on any feature.
+> `dotnet test` fails on either — the rules are NetArchTest fitness functions, not a wiki page.
+
+Those two facts are exactly what makes extraction possible later. A feature nobody reached into
+can be moved whole; a kernel that names no feature travels with it instead of holding it back.
+
+**Calling another feature through its front door is allowed.** That is the difference between
+this style and vertical slices — you are paying for a single deployable, so take the cheap
+in-process call. Every one of those calls is a line you will have to make remote on the day you
+split, which is why they go through an interface you control rather than into someone's internals.
+
+## Layout
+
+```
+src/<Solution>.Api/
+  Kernel/                          # the shared kernel: depends on nothing above it
+    AppException.cs                #   one failure shape, with a transport-agnostic code
+  Features/
+    {{ featureName | pascal }}/
+      {{ featureName | pascal }}Feature.cs         # THE FRONT DOOR — interface + read model
+      {{ featureName | pascal }}Registration.cs    # the feature wires itself into DI
+      Internal/
+        {{ featureName | pascal }}Service.cs       # `internal sealed`; private to the feature
+tests/ArchitectureTests/
+  FeatureBoundaryTests.cs
+```
+
+Wire it up with one line in `Program.cs`:
+
+```csharp
+builder.Services.Add{{ featureName | pascal }}Feature();
+```
+
+Add a feature by copying the folder and adding another `Add…Feature()` call. The test discovers
+feature namespaces by reflection, so there is nothing to register in the test project.
+
+## Enforcement
+
+`dotnet test` runs `tests/ArchitectureTests`, which asserts that:
+
+- nothing outside `Features.<Name>` depends on `Features.<Name>.Internal`,
+- `Kernel` depends on no feature,
+- no type in an `.Internal` namespace is public,
+- at least one feature was discovered — an empty assembly must not pass silently.
+
+`internal` alone is not the boundary here: everything in one assembly can see everything else
+that is `internal`. The namespace rule is what actually holds, which is why it is a test.
+
+## Kernel admission rule (not mechanically enforced)
+
+A thing moves into `Kernel/` when **a second feature needs it AND it names no feature**. The
+tests enforce the second half only. Nothing can prove the first half for you, so it belongs in
+review: a kernel that grows by one type per feature has become a `Common/` dumping ground, and
+that is the failure mode this style dies of.
+
+The folder is `Kernel`, not `Shared`, because CA1716 rejects a namespace whose name collides
+with a language keyword.
+
+## When to stop using this
+
+Split a feature into its own project — then its own service — when two teams block on the same
+pipeline, or when one feature measurably needs an order of magnitude more capacity than the
+rest. Until then the deploy queue is not the constraint.
+
+Sources: [Fowler — MonolithFirst](https://martinfowler.com/bliki/MonolithFirst.html) ·
+[Microsoft Learn — common web application architectures](https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures) ·
+[NetArchTest](https://github.com/BenMorris/NetArchTest).

package/templates/architectures/monolith/files/docs/architecture/monolith.go.md

@@ -0,0 +1,69 @@
+# Architecture — Monolith (single deployable)
+
+One binary, one release train, partitioned into features over a deliberately small shared
+kernel. This is the start-here layout: cheap enough that a small team is not paying for
+boundaries it does not need yet, seamed so a feature can be lifted out later.
+
+## The one rule that matters
+
+> **A feature is entered through its front door, and the kernel never walks through it.**
+>
+> From outside `internal/features/<name>`, the only importable package is that feature's root
+> package. `internal/shared/...` may not import a feature at all. `go build` enforces the first
+> rule for the nested `internal/` subtree; `go test ./...` enforces both everywhere else.
+
+Those two facts are exactly what makes extraction possible later. A feature nobody reached into
+can be moved whole; a kernel that names no feature travels with it instead of holding it back.
+
+**Calling another feature through its front door is allowed.** That is the difference between
+this style and vertical slices — you are paying for a single binary, so take the cheap
+in-process call. Every one of those calls is a line you will have to make remote on the day you
+split, which is why they go through an interface you control rather than into someone's internals.
+
+## Layout
+
+```
+internal/
+  shared/
+    apperr/apperr.go             # the kernel: one failure shape; depends on nothing above it
+  features/
+    features.go                  # composition root: the only package that knows all features
+    {{ featureName | lower }}/
+      {{ featureName | lower }}.go               # THE FRONT DOOR — interface, read model, New()
+      internal/
+        store/store.go           # private; the compiler refuses this import from outside
+  architecture/
+    boundary_test.go             # the fitness test
+```
+
+Add a feature by copying `features/{{ featureName | lower }}/` and adding a field to `Set`; the
+test walks the tree, so there is nothing else to register.
+
+## Enforcement
+
+```
+go build ./...    # fails on any import of another feature's internal/ subtree
+go test ./...     # runs internal/architecture: front-door rule + kernel rule, plus a self-test
+```
+
+Go gives you half of this for free: a package under `internal/` is importable only from the
+subtree rooted at its parent. The test covers what the compiler does not — a subpackage that
+happens **not** to sit under `internal/`, and the kernel importing a feature.
+`ARCH_FEATURES_SEGMENT` and `ARCH_SHARED_SEGMENT` move the roots.
+
+## Kernel admission rule (not mechanically enforced)
+
+A package moves into `internal/shared/` when **a second feature needs it AND it names no
+feature**. The test enforces the second half only. Nothing can prove the first half for you, so
+it belongs in review: a kernel that grows by one package per feature has become a `common/`
+dumping ground, and that is the failure mode this style dies of.
+
+## When to stop using this
+
+Split a feature out when two teams block on the same pipeline, or when one feature measurably
+needs an order of magnitude more capacity than the rest — not before. Until then the deploy
+queue is not the constraint, and every distributed failure mode you have not bought is a win.
+
+Sources: [Fowler — MonolithFirst](https://martinfowler.com/bliki/MonolithFirst.html) ·
+[Fowler — MicroservicePremium](https://martinfowler.com/bliki/MicroservicePremium.html) ·
+[go command — internal directories](https://pkg.go.dev/cmd/go#hdr-Internal_Directories).

package/templates/architectures/monolith/files/docs/architecture/monolith.node.md

@@ -0,0 +1,70 @@
+# Architecture — Monolith (single deployable)
+
+One process, one release train, partitioned into features over a deliberately small shared
+kernel. This is the start-here layout: cheap enough that a small team is not paying for
+boundaries it does not need yet, seamed so a feature can be lifted out later.
+
+## The one rule that matters
+
+> **A feature is entered through its front door, and the kernel never walks through it.**
+>
+> From outside `src/features/<name>/`, the only importable file is that feature's `index.ts`.
+> Nothing in `src/shared/` may import a feature at all. `scripts/check-monolith-boundaries.mjs`
+> exits non-zero on either, so the build fails rather than the wiki being ignored.
+
+Those two facts are exactly what makes extraction possible later. A feature nobody reached into
+can be moved whole; a kernel that names no feature travels with it instead of holding it back.
+
+**Calling another feature through its front door is allowed.** That is the difference between
+this style and vertical slices — you are paying for a single deployable, so take the cheap
+in-process call. Every one of those calls is a line you will have to make remote on the day you
+split, which is why they go through a surface you control rather than into someone's internals.
+
+## Layout
+
+```
+src/
+  shared/                      # the kernel: depends on nothing above it
+    index.ts                   #   its published surface
+    errors.ts                  #   AppError — one failure shape for every feature
+  features/
+    index.ts                   # composition root: the only file that knows all features
+    {{ featureName | kebab }}/
+      index.ts                 #   THE FRONT DOOR — contract + factory
+      {{ featureName | kebab }}.service.ts        #   private; add files beside it freely
+scripts/
+  check-monolith-boundaries.mjs
+```
+
+Add a feature by copying `features/{{ featureName | kebab }}/` and adding a line to
+`features/index.ts`; the checker discovers any directory under the feature root, so there is
+nothing else to register.
+
+## Enforcement
+
+```
+node scripts/check-monolith-boundaries.mjs      # add to CI and to `npm run check:boundaries`
+node scripts/check-monolith-boundaries.mjs --self-test   # proves the rule still fires
+```
+
+It reads import specifiers as written and never resolves them on disk, so it is immune to
+TypeScript and bundler resolution differences, and it has no dependencies. `ARCH_FEATURES_ROOT`,
+`ARCH_SHARED_ROOT` and `ARCH_SCAN_ROOTS` move the roots — set them when the app lives under
+`apps/<name>/src` in a monorepo. Finding zero features is a failure, not a pass.
+
+## Kernel admission rule (not mechanically enforced)
+
+A thing moves into `shared/` when **a second feature needs it AND it names no feature**. The
+checker enforces the second half only. Nothing can prove the first half for you, so it belongs
+in review: a kernel that grows by one file per feature has become a `common/` dumping ground,
+and that is the failure mode this style dies of.
+
+## When to stop using this
+
+Split a feature out when two teams block on the same pipeline, or when one feature measurably
+needs an order of magnitude more capacity than the rest — not before. Until then the deploy
+queue is not the constraint, and every distributed failure mode you have not bought is a win.
+
+Sources: [Fowler — MonolithFirst](https://martinfowler.com/bliki/MonolithFirst.html) ·
+[Fowler — MicroservicePremium](https://martinfowler.com/bliki/MicroservicePremium.html) ·
+[Signal v. Noise — The Majestic Monolith](https://signalvnoise.com/svn3/the-majestic-monolith/).