@opengroundplan/core 0.1.1

package/templates/architectures/llm-workflow/files/src/workflow/routing/route.ts

@@ -0,0 +1,38 @@
+import type { StepContext } from '../types.js';
+
+export type Route = 'single' | 'chunked';
+
+export interface Routed {
+  kind: Route;
+  chunks: string[];
+}
+
+/**
+ * Routing is a cheap deterministic classifier in code. Where a classification genuinely needs a
+ * model, make it its own step and route on that step's output — never inline the call here, or
+ * the branch stops being reproducible.
+ */
+export function route(input: string, ctx: StepContext): Routed {
+  const text = input.trim();
+  if (text === '') return { kind: 'single', chunks: [] };
+  if (text.length <= ctx.chunkChars) return { kind: 'single', chunks: [text] };
+  return { kind: 'chunked', chunks: pack(text.split(/\s+/), ctx.chunkChars) };
+}
+
+/** Packs on word boundaries; a single word over the limit becomes its own chunk. */
+function pack(words: string[], limit: number): string[] {
+  const chunks: string[] = [];
+  let current = '';
+
+  for (const word of words) {
+    const candidate = current === '' ? word : `${current} ${word}`;
+    if (candidate.length <= limit || current === '') {
+      current = candidate;
+    } else {
+      chunks.push(current);
+      current = word;
+    }
+  }
+  if (current !== '') chunks.push(current);
+  return chunks;
+}

package/templates/architectures/llm-workflow/files/src/workflow/settings.ts

@@ -0,0 +1,44 @@
+/**
+ * The only module in the workflow that reads the environment. Steps, chains, routing and
+ * parallel code receive what they need through the context instead.
+ */
+
+const PREFIX = '{{ solutionName | upperSnake }}_WORKFLOW_';
+
+export interface WorkflowSettings {
+  /** Which provider binding `resolveLlm()` builds. */
+  binding: string;
+  promptsDir: string;
+  goldensFile: string;
+  /** Longest chunk a single model call is given before the chain fans out. */
+  chunkChars: number;
+  maxParallel: number;
+  maxOutputTokens: number;
+  timeoutMs: number;
+}
+
+function text(name: string, fallback: string): string {
+  const raw = process.env[PREFIX + name];
+  return raw !== undefined && raw.trim() !== '' ? raw.trim() : fallback;
+}
+
+function count(name: string, fallback: number): number {
+  const raw = Number(process.env[PREFIX + name]);
+  return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+
+let cached: WorkflowSettings | undefined;
+
+/** One typed default table. Every value is overridable by `{{ solutionName | upperSnake }}_WORKFLOW_<FIELD>`. */
+export function settings(): WorkflowSettings {
+  cached ??= {
+    binding: text('BINDING', 'stub'),
+    promptsDir: text('PROMPTS_DIR', '{{ promptsDir }}'),
+    goldensFile: text('GOLDENS_FILE', 'src/workflow/evals/goldens.jsonl'),
+    chunkChars: count('CHUNK_CHARS', 2000),
+    maxParallel: count('MAX_PARALLEL', 4),
+    maxOutputTokens: count('MAX_OUTPUT_TOKENS', 1024),
+    timeoutMs: count('TIMEOUT_MS', 60_000),
+  };
+  return cached;
+}

package/templates/architectures/llm-workflow/files/src/workflow/steps/__firstStep.kebab__.ts

@@ -0,0 +1,19 @@
+import { loadPrompt } from '../prompts.js';
+import type { Step } from '../types.js';
+
+/**
+ * One model call, one purpose. The provider arrives on the context — a step that constructs its
+ * own client cannot be pointed at a different model for an eval run.
+ *
+ * The prompt name and version are literals here on purpose: the boundary check reads them
+ * statically and fails when the pinned version has no file behind it.
+ */
+export const {{ firstStep | camel }}Step: Step<string, string> = async (chunk, ctx) => {
+  const completion = await ctx.llm.complete({
+    role: '{{ firstStep | kebab }}',
+    system: loadPrompt('{{ firstStep | kebab }}', '{{ promptVersion }}'),
+    user: chunk,
+    maxOutputTokens: ctx.maxOutputTokens,
+  });
+  return completion.text;
+};

package/templates/architectures/llm-workflow/files/src/workflow/steps/index.ts

@@ -0,0 +1,3 @@
+/** The step surface chains compose against. Steps never import each other. */
+export { {{ firstStep | camel }}Step } from './{{ firstStep | kebab }}.js';
+export { normalizeStep } from './normalize.js';

package/templates/architectures/llm-workflow/files/src/workflow/steps/normalize.ts

@@ -0,0 +1,8 @@
+import type { Step } from '../types.js';
+
+/** Not every step calls a model. A deterministic one keeps the chain's tail assertable. */
+export const normalizeStep: Step<readonly string[], string> = async (parts) =>
+  parts
+    .map((part) => part.trim().split(/\s+/).join(' '))
+    .filter((part) => part !== '')
+    .join(' | ');

package/templates/architectures/llm-workflow/files/src/workflow/types.ts

@@ -0,0 +1,29 @@
+import { resolveLlm } from './ports/index.js';
+import type { LlmPort } from './ports/llm.js';
+import { settings } from './settings.js';
+
+/**
+ * Everything a step is allowed to depend on. A step that needs something else takes it as an
+ * argument — reaching for the environment or a module singleton is what the boundary check
+ * rejects.
+ */
+export interface StepContext {
+  llm: LlmPort;
+  chunkChars: number;
+  maxParallel: number;
+  maxOutputTokens: number;
+}
+
+/** One composable unit. Steps never call each other; chains, routing and parallel compose them. */
+export type Step<In, Out> = (input: In, ctx: StepContext) => Promise<Out>;
+
+/** Per-request overrides on top of the settings defaults. */
+export function createContext(overrides: Partial<StepContext> = {}): StepContext {
+  const config = settings();
+  return {
+    llm: overrides.llm ?? resolveLlm(),
+    chunkChars: overrides.chunkChars ?? config.chunkChars,
+    maxParallel: overrides.maxParallel ?? config.maxParallel,
+    maxOutputTokens: overrides.maxOutputTokens ?? config.maxOutputTokens,
+  };
+}

package/templates/architectures/llm-workflow/files/tests/test_workflow_boundaries.py

@@ -0,0 +1,171 @@
+"""The one rule of this architecture, enforced instead of documented.
+
+A step may not call a model directly — it goes through the provider seam in ``workflow/ports``,
+so a model can be swapped and re-evaluated without editing a step. Checked by reading the
+source, so it holds with no extra dependency installed.
+"""
+
+from __future__ import annotations
+
+import ast
+import shutil
+import subprocess
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+WORKFLOW = REPO_ROOT / "src" / "{{ solutionName | snake }}" / "workflow"
+PORTS = WORKFLOW / "ports"
+SETTINGS = WORKFLOW / "settings.py"
+PROMPTS = REPO_ROOT / "{{ promptsDir }}"
+GOLDENS = WORKFLOW / "evals" / "goldens.jsonl"
+
+# Vendor SDKs and raw HTTP clients. Only the ports package may name any of these.
+MODEL_ACCESS = frozenset(
+    {
+        "anthropic", "openai", "cohere", "groq", "ollama", "mistralai", "replicate",
+        "google", "boto3", "botocore", "langchain", "langchain_core", "llama_index",
+        "httpx", "requests", "aiohttp", "urllib", "urllib3", "http", "socket",
+    }
+)
+
+# Composition flows one way; a step is a leaf.
+STEP_FORBIDDEN_PREFIXES = ("steps", "chains", "routing", "parallel")
+
+
+def _sources() -> list[Path]:
+    return sorted(WORKFLOW.rglob("*.py"))
+
+
+def _top_level_imports(tree: ast.AST) -> set[str]:
+    found: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            found.update(alias.name.split(".")[0] for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            found.add(node.module.split(".")[0])
+    return found
+
+
+def _relative_target(file: Path, node: ast.ImportFrom) -> str | None:
+    """Resolve a relative import to a dotted path below ``workflow/``."""
+    if node.level == 0:
+        return None
+    package = list(file.relative_to(WORKFLOW).parent.parts)
+    up = node.level - 1
+    if up > len(package):
+        return None
+    base = package[: len(package) - up]
+    if node.module:
+        base += node.module.split(".")
+    return ".".join(base)
+
+
+def test_only_ports_reach_a_model() -> None:
+    violations: list[str] = []
+
+    for file in _sources():
+        if PORTS in file.parents:
+            continue
+        tree = ast.parse(file.read_text(encoding="utf-8"))
+        for module in sorted(_top_level_imports(tree) & MODEL_ACCESS):
+            violations.append(
+                f"{file.relative_to(REPO_ROOT)}: imports {module!r} — only workflow/ports may "
+                f"reach a model. Take an LlmPort on the step context instead."
+            )
+
+    assert not violations, "\n".join(violations)
+
+
+def test_only_settings_reads_the_environment() -> None:
+    violations: list[str] = []
+
+    for file in _sources():
+        if file == SETTINGS:
+            continue
+        tree = ast.parse(file.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if (
+                isinstance(node, ast.Attribute)
+                and isinstance(node.value, ast.Name)
+                and node.value.id == "os"
+                and node.attr in {"environ", "getenv"}
+            ):
+                violations.append(
+                    f"{file.relative_to(REPO_ROOT)}:{node.lineno}: reads the environment — "
+                    f"configuration belongs in workflow/settings.py"
+                )
+
+    assert not violations, "\n".join(violations)
+
+
+def test_steps_are_leaves() -> None:
+    violations: list[str] = []
+
+    for file in sorted((WORKFLOW / "steps").rglob("*.py")):
+        # The package barrel exists to re-export steps, so it may import them.
+        if file.name == "__init__.py":
+            continue
+        tree = ast.parse(file.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ImportFrom):
+                continue
+            target = _relative_target(file, node)
+            if target is not None and target.startswith(STEP_FORBIDDEN_PREFIXES):
+                violations.append(
+                    f"{file.relative_to(REPO_ROOT)}:{node.lineno}: step imports {target!r} — "
+                    f"compose steps in a chain, never inside another step"
+                )
+
+    assert not violations, "\n".join(violations)
+
+
+def test_every_pinned_prompt_version_exists() -> None:
+    """A pinned prompt with no file behind it fails at the first request instead of in CI."""
+    violations: list[str] = []
+
+    for file in _sources():
+        tree = ast.parse(file.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if not (isinstance(node, ast.Call) and isinstance(node.func, ast.Name)):
+                continue
+            if node.func.id != "load_prompt" or len(node.args) != 2:
+                continue
+            name, version = node.args
+            if not (isinstance(name, ast.Constant) and isinstance(version, ast.Constant)):
+                violations.append(
+                    f"{file.relative_to(REPO_ROOT)}:{node.lineno}: load_prompt() needs literal "
+                    f"arguments so the pinned version is checkable"
+                )
+                continue
+            prompt = PROMPTS / str(name.value) / f"{version.value}.md"
+            if not prompt.is_file():
+                violations.append(
+                    f"{file.relative_to(REPO_ROOT)}:{node.lineno}: no prompt file at "
+                    f"{prompt.relative_to(REPO_ROOT)}"
+                )
+
+    assert not violations, "\n".join(violations)
+
+
+def test_golden_dataset_is_checked_in() -> None:
+    assert GOLDENS.is_file(), f"{GOLDENS} is missing — the dataset is committed, not generated"
+    lines = [
+        line
+        for line in GOLDENS.read_text(encoding="utf-8").splitlines()
+        if line.strip() and not line.strip().startswith("#")
+    ]
+    assert lines, "the golden dataset has no cases — an empty dataset is not a passing suite"
+
+
+def test_import_contracts_hold() -> None:
+    """Runs the same contracts as `lint-imports`, so a plain `pytest` also catches them."""
+    linter = shutil.which("lint-imports")
+    if linter is None:
+        # Skipping would mean the layering is unenforced and nobody notices.
+        raise AssertionError("import-linter is not installed. Run: uv add --dev import-linter")
+
+    # Fixed argv, no shell.
+    result = subprocess.run(
+        [linter], cwd=REPO_ROOT, capture_output=True, text=True, check=False
+    )
+    assert result.returncode == 0, result.stdout + result.stderr

package/templates/architectures/llm-workflow/files/tests/test_workflow_goldens.py

@@ -0,0 +1,30 @@
+"""The golden suite as a test, so `pytest` fails when the orchestration drifts.
+
+Runs against the stub binding: no key, no network, no flakiness. What it guards is the code
+path — routing, fan-out order, and the deterministic tail — not the model's answer.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+
+from {{ solutionName | snake }}.workflow.evals.runner import run_goldens
+from {{ solutionName | snake }}.workflow.prompts import load_prompt
+from {{ solutionName | snake }}.workflow.settings import ENV_PREFIX, get_settings
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_golden_cases_pass() -> None:
+    # Settings hold repo-relative paths; pin them absolutely so the suite passes from any cwd.
+    os.environ[ENV_PREFIX + "PROMPTS_DIR"] = str(REPO_ROOT / "{{ promptsDir }}")
+    os.environ[ENV_PREFIX + "GOLDENS_FILE"] = str(
+        REPO_ROOT / "src" / "{{ solutionName | snake }}" / "workflow" / "evals" / "goldens.jsonl"
+    )
+    get_settings.cache_clear()
+    load_prompt.cache_clear()
+
+    failures = asyncio.run(run_goldens())
+    assert not failures, "\n".join(failures)

package/templates/architectures/medallion/blueprint.yaml

@@ -0,0 +1,91 @@
+id: medallion
+kind: architecture
+name: Medallion (Bronze / Silver / Gold)
+description: >-
+  Lakehouse overlay that splits a pipeline into bronze (raw, immutable, replayable), silver
+  (deduplicated, conformed, referentially intact) and gold (business aggregates), with a data
+  contract per layer recording what that layer actually guarantees. Boundaries are mechanical:
+  an import-linter layers contract plus a skip-layer ban, a stdlib AST fitness test for the
+  read-down rule, and a contract test that rejects a silver layer promising no more than bronze.
+
+tags:
+  - medallion
+  - lakehouse
+  - bronze-silver-gold
+  - data-contracts
+  - boundaries
+  - import-linter
+
+requires: []
+conflicts: []
+provides:
+  - medallion-layers
+  - data-contracts
+  - architecture-overlay
+
+# Meaningless on an overlay: this blueprint *is* the architecture.
+supportsArchitectures: []
+
+variables:
+  # The layout says nothing without one dataset flowing through all three layers.
+  - name: firstDataset
+    prompt: Name of the first dataset to flow bronze -> silver -> gold (e.g. "orders")
+    type: string
+    default: orders
+    required: false
+
+  - name: pythonPackageManager
+    prompt: Python package manager
+    type: select
+    default: uv
+    required: false
+    when: "stack == 'python'"
+    choices:
+      - { value: uv, label: uv }
+      - { value: pip, label: pip }
+      - { value: poetry, label: poetry }
+
+# python only. The catalog rates typescript, node and go `awkward` for this pattern, so no
+# layout is emitted for them — a folder skeleton for a stack the pattern fights is a trap.
+files:
+  - from: files/docs/architecture/medallion.python.md
+    to: .
+    when: "stack == 'python'"
+
+  # The contracts are the deliverable, not documentation of it: the pipelines load them at
+  # runtime and the fitness test fails on them.
+  - from: files/contracts/*.contract.toml
+    to: .
+    when: "stack == 'python'"
+
+  - from: files/src/__solutionName.snake__/pipelines/**
+    to: .
+    when: "stack == 'python'"
+
+  - from: files/tests/architecture/*.py
+    to: .
+    when: "stack == 'python'"
+
+  # .importlinter, not pyproject.toml, so the base keeps sole ownership of its packaging file.
+  - 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).
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+postApply:
+  # The contract file is useless without the linter that reads it. The AST tests need nothing.
+  - run: uv add --dev "import-linter==2.13"
+    when: "stack == 'python' && pythonPackageManager == 'uv'"
+    optional: true
+  - run: python -m pip install "import-linter==2.13"
+    when: "stack == 'python' && pythonPackageManager == 'pip'"
+    optional: true
+  - run: poetry add --group dev "import-linter==2.13"
+    when: "stack == 'python' && pythonPackageManager == 'poetry'"
+    optional: true

package/templates/architectures/medallion/files/.importlinter

@@ -0,0 +1,31 @@
+# Medallion boundaries, enforced by import-linter. Run `lint-imports`.
+# The package must be importable, so run `uv sync` (or `pip install -e .`) first.
+# The read-down rule for code *outside* the pipelines package is enforced by
+# tests/architecture/test_medallion_boundaries.py — import-linter cannot express "everything
+# except this package".
+[importlinter]
+root_package = {{ solutionName | snake }}
+
+[importlinter:contract:medallion-layers]
+name = Data flows upward only — no layer may import a layer above it
+type = layers
+containers =
+    {{ solutionName | snake }}.pipelines
+# Highest first.
+layers =
+    gold
+    silver
+    bronze
+
+# The layers contract permits gold to reach past silver; medallion does not. Gold reads
+# conformed data or it is reimplementing silver's dedup and referential integrity by hand.
+[importlinter:contract:no-skip-layer]
+name = Gold reads silver, never bronze
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.pipelines.gold
+forbidden_modules =
+    {{ solutionName | snake }}.pipelines.bronze
+# Direct imports only. gold -> silver -> bronze is the architecture working, not a violation,
+# and forbidden contracts flag indirect chains unless told otherwise.
+allow_indirect_imports = True

package/templates/architectures/medallion/files/contracts/bronze.contract.toml

@@ -0,0 +1,16 @@
+# What bronze GUARANTEES to silver. Nothing above may assume more than what is written here.
+layer = "bronze"
+# Empty: bronze reads source systems, not another layer.
+reads_from = ""
+owner = "{{ solutionName | title }} data platform"
+
+# Bronze promises fidelity, not quality. Adding "deduplicated" or "schema_enforced" here is a
+# lie the fitness test cannot catch — it can only catch the reverse. Keep this list honest.
+guarantees = ["replayable", "append_only", "lineage_stamped"]
+
+[[datasets]]
+name = "{{ firstDataset | snake }}"
+source = "set me — the system of record this lands from"
+format = "set me — json, avro, parquet, cdc"
+# No business_key on purpose: bronze has no keys. Rows are whatever arrived, duplicates and all.
+# assert_contract() rejects a bronze dataset that declares one.

package/templates/architectures/medallion/files/contracts/gold.contract.toml

@@ -0,0 +1,21 @@
+# What gold GUARANTEES to BI, dashboards and downstream products.
+#
+# Gold is where dimensional modelling lives — star schemas and data marts are built here, not
+# instead of this pattern. Gold is derived and disposable: every run replaces it from silver.
+layer = "gold"
+reads_from = "silver"
+owner = "{{ solutionName | title }} data platform"
+
+guarantees = [
+    # Each measure has one owned, versioned definition. Two dashboards cannot disagree on it.
+    "business_defined",
+    # Every aggregate reconciles to the silver rows behind it at the declared grain.
+    "aggregate_consistent",
+]
+
+[[datasets]]
+name = "{{ firstDataset | snake }}_daily"
+source_dataset = "{{ firstDataset | snake }}"
+# Required. A gold table with no stated grain is a table nobody can reconcile or trust.
+grain = ["event_date"]
+measures = ["{{ firstDataset | snake }}_count"]

package/templates/architectures/medallion/files/contracts/silver.contract.toml

@@ -0,0 +1,31 @@
+# What silver GUARANTEES to gold and to every analyst querying it directly.
+#
+# This file exists to answer one question honestly: is silver trustworthy, or is it bronze with
+# a filter on it? Everything listed under `guarantees` is a promise something upstream must
+# actually do. `tests/architecture/test_layer_contracts.py` fails if the four required silver
+# guarantees are absent, and fails if a dataset claims dedup without a key to dedup on.
+layer = "silver"
+reads_from = "bronze"
+owner = "{{ solutionName | title }} data platform"
+
+guarantees = [
+    # Every column is typed. A row that will not parse is rejected, never coerced to null.
+    "schema_enforced",
+    # Exactly one row per business_key below.
+    "deduplicated",
+    # Codes, units, currencies and timestamps normalised to the shared vocabulary.
+    "conformed",
+    # Every foreign key in `references` resolves. An orphan row is rejected, not nulled.
+    "referential_integrity",
+    # Out-of-order arrivals are reconciled into the existing row, not appended as a new one.
+    "late_data_handled",
+]
+
+[[datasets]]
+name = "{{ firstDataset | snake }}"
+# Required. Deduplication without a declared key is a claim, not a guarantee.
+business_key = ["{{ firstDataset | snake }}_id"]
+# Foreign keys this dataset promises to resolve, as "dataset.column".
+references = []
+# Timestamp used to pick the surviving row when the same key arrives twice.
+version_column = "_ingested_at"

package/templates/architectures/medallion/files/docs/architecture/medallion.python.md

@@ -0,0 +1,104 @@
+# Architecture — Medallion (Bronze / Silver / Gold)
+
+Data is refined in three hops. Each hop is a package, each package has a written contract, and
+two build-failing checks keep the hops from collapsing into each other.
+
+## The one rule that matters
+
+> **A layer may only read the layer directly below it, and it must guarantee, in writing, more
+> than that layer did.** Bronze reads sources. Silver reads bronze. Gold reads silver. Gold
+> reaching into bronze is not a shortcut — it is silver's dedup and referential integrity being
+> reimplemented by hand somewhere nobody audits.
+
+The second half of that rule is the one that gets skipped. `contracts/silver.contract.toml`
+exists so "silver is cleaner than bronze" has to be spelled out as specific promises —
+deduplicated on a named key, schema enforced, conformed, referentially intact — and
+`tests/architecture/test_layer_contracts.py` fails when it is not. **Silver that is bronze with
+a filter on it is the standard way this architecture fails.**
+
+## Layout
+
+```
+contracts/
+  bronze.contract.toml            # what bronze guarantees silver
+  silver.contract.toml            # what silver guarantees gold — the load-bearing one
+  gold.contract.toml              # what gold guarantees BI
+src/{{ solutionName | snake }}/pipelines/
+  config.py                       # the one typed default table for the lakehouse
+  contracts.py                    # contract loader + the guarantee vocabulary + assert_contract
+  io.py                           # LakehouseIO Protocol — the engine seam
+  run.py                          # orchestration seam: the only module that may touch all three
+  bronze/
+    ingest.py                     # land() — append-only, lineage-stamped, no transformation
+  silver/
+    conform.py                    # conform() — dedupe on the contract's business key
+  gold/
+    aggregate.py                  # aggregate() — rebuild at the contract's grain, from silver
+tests/architecture/
+  test_medallion_boundaries.py    # the read-down rule
+  test_layer_contracts.py         # the contracts actually promise something
+.importlinter                     # the same rule, in the standard tool
+```
+
+## What each layer is for
+
+| Layer | Contains | Guarantees | Audience |
+|---|---|---|---|
+| **Bronze** | Source data exactly as it arrived, plus lineage columns. Append-only, CDC and history retained. | Replayable, append-only, lineage-stamped. **Not** deduplicated, **not** typed. | Engineers, audit, reprocessing |
+| **Silver** | Deduplicated, schema-enforced, conformed, referentially intact. Merged on a business key so re-runs converge. | The four above, plus late-arrival handling. | Analysts, data science, ad-hoc |
+| **Gold** | Business aggregates, star schemas, data marts. Derived and disposable — overwritten each run. | Owned metric definitions; aggregates reconcile to silver. | BI, dashboards, products |
+
+Two things this layout deliberately does not do. **Nothing writes directly to silver from
+ingestion** — a schema change or a corrupt record then has no raw copy to replay from. And
+**gold does not replace dimensional modelling**; star schemas live *in* gold, they are not an
+alternative to it.
+
+## Enforcement — three checks, all of which fail a command
+
+1. **`pytest tests/architecture/test_medallion_boundaries.py`** — stdlib AST walk over `src/`.
+   Fails on an upward import (`silver` → `gold`), a skipped layer (`gold` → `bronze`), and on
+   application code outside `pipelines/` importing `bronze` at all. Runs standalone with nothing
+   installed: `python tests/architecture/test_medallion_boundaries.py`.
+2. **`pytest tests/architecture/test_layer_contracts.py`** — loads all three contracts and fails
+   if a layer omits its required guarantees, if silver claims deduplication with no
+   `business_key`, if a gold dataset has no `grain`, if bronze declares a key it has no business
+   having, or if `reads_from` names anything but the layer directly below.
+3. **`lint-imports`** — `.importlinter` states the same rule in the standard tool: a `layers`
+   contract over `pipelines` plus a `forbidden` contract banning `gold` → `bronze`.
+
+Run the tests from the repo root; contracts resolve relative to the working directory.
+
+## What is not enforced mechanically
+
+Three gaps, stated plainly rather than pretended away:
+
+- **A contract can overclaim.** `assert_contract` proves silver *says* it deduplicates and has a
+  key to do it with; it cannot prove the pipeline actually did. Close that with per-dataset data
+  quality assertions in the job itself (row counts, key uniqueness, orphan checks) — the
+  `Conformer` seam in `silver/conform.py` is where they belong.
+- **Layer boundaries in SQL and notebooks are invisible.** Both checks read Python imports. A
+  notebook or a `SELECT` that reads a bronze table straight into a dashboard is outside their
+  reach; enforce that with warehouse-side grants, not with review.
+- **Storage layout is convention.** `config.dataset_path()` puts each layer under its own prefix,
+  but nothing stops a job writing elsewhere. Grant write permission per layer prefix if the
+  storage backend supports it.
+
+## Configuration
+
+Every lakehouse setting lives in `pipelines/config.py` and is overridable by environment
+variable with the `{{ solutionName | upperSnake }}_LAKE_` prefix — `ROOT`, `CONTRACTS_DIR`,
+`MAX_REJECT_RATIO`, `DRY_RUN`. Nothing else reads the environment. Add the lake root to
+`.gitignore`; it is data, not source.
+
+## Adding a dataset
+
+1. Add a `[[datasets]]` block to each layer's contract, bottom up. Silver needs a
+   `business_key`; gold needs a `grain`.
+2. Call `land()`, then `conform()`, then `aggregate()` from `pipelines/run.py`.
+3. Run the two architecture tests. If they fail, the contract and the code disagree — that is
+   the point.
+
+Sources: [Databricks, Medallion architecture](https://www.databricks.com/glossary/medallion-architecture) ·
+[Databricks docs, Lakehouse medallion](https://docs.databricks.com/aws/en/lakehouse/medallion) ·
+[Microsoft Learn, Azure Databricks medallion](https://learn.microsoft.com/en-us/azure/databricks/lakehouse/medallion) ·
+[import-linter](https://import-linter.readthedocs.io/).

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

@@ -0,0 +1,2 @@
+[project]
+dependencies = ["deltalake>=1.6.2"]

package/templates/architectures/medallion/files/src/__solutionName.snake__/pipelines/__init__.py

@@ -0,0 +1,5 @@
+"""Medallion pipelines: bronze (raw) -> silver (conformed) -> gold (business).
+
+A layer may only read the layer directly below it. Modules directly under this package are the
+orchestration seam and may touch every layer; nothing outside it may import bronze.
+"""

package/templates/architectures/medallion/files/src/__solutionName.snake__/pipelines/bronze/__init__.py

@@ -0,0 +1,5 @@
+"""Bronze — raw, immutable, replayable. Lands source data exactly as it arrived.
+
+Bronze may import no other layer. It promises fidelity, not quality: no dedup, no schema
+enforcement, no joins. Everything downstream can be rebuilt by replaying it.
+"""