SAMA 2.0 — Voorstel voor de volgende evolutie

Hier is een uitgewerkte, concrete versie van SAMA 2.0. Ik houd de kern intact (want die is sterk), maar maak het completer, toekomstbestendiger en nog beter geschikt voor agentic coding in 2026+.
Kern blijft hetzelfde (de vier letters)

    S — Sorted: Alphabetical + dependency direction (lager nummer importeert nooit hoger).

    A — Architecture: Numerieke lagen met duidelijke contracten.

    M — Modeled: Types + sibling tests.

    A — Atomic: Bestanden klein houden (~700 regels) + split per domein.

Wat verandert / wordt toegevoegd in 2.0

Ik voeg twee nieuwe letters toe → SAMA wordt SAMAX (of je houdt SAMA en maakt de extra’s optioneel).
Nieuwe letter: X — eXtensible & Vertical

    Doel: Combineer de kracht van horizontale lagen (duidelijke dependency flow) met verticale slices (alles van één feature dicht bij elkaar).

    Regel: Optionele feature-prefix bovenop de laag: c32_user_auth.ts of feat_payment_c32_processor.ts.

    Voordeel voor agents: Een agent die aan “user authentication” werkt, ziet alle relevante bestanden gegroepeerd via zoekopdracht feat_user_*.

Nieuwe letter: D — Documented (de vijfde discipline)

    Regel: Elke module én elke feature-map heeft een README.md of .agent.md met:

        One-sentence responsibility

        Key types & contracts

        Acceptance criteria / invariants

        “Where to put new code” instructies

    Dit wordt de levende specificatie voor de agent.

Uitgebreide Layer Mapping (Architecture 2.0)
Laag	Naam	Verantwoordelijkheid	Voorbeelden	Mag importeren van
c11	Entry / Composition Root	App bootstrap, wiring	main.ts, server.ts	Alles
c13	Data / Persistence	DB, repositories, queries	c13_user_repo.ts	c31
c14	I/O Adapters	HTTP, queues, external APIs	c14_auth_controller.ts	c21, c31, c32
c21	Handlers / Presenters	Request/response orchestration	c21_login_handler.ts	c32, c31
c31	Models & Types	Domain models, DTOs, Value Objects, Zod schemas	c31_user.ts	- (puur)
c32	Business Logic / Use Cases	Pure functions, domain rules	c32_user_auth.ts	c31
c40	Application Services	Orchestratie van meerdere use cases (nieuw!)	c40_user_service.ts	c32, c31
c51	UI / Presentation	Components, pages, server components	c51_user_profile.tsx	c31, c32
c60	Infrastructure / External	Third-party clients, config, logging	c60_stripe_client.ts	-
c70	Cross-cutting	Auth middleware, logging, monitoring, tracing	c70_logger.ts	alles (voorzichtig)

Atomic-regel verfijnd: Max ~600-700 regels of max 1 feature per bestand (zelfs als het kleiner is).
Tooling & Automatisering (kritisch voor gold standard)

SAMA 2.0 moet dit hebben:

    Officiële sama CLI

        sama check → voert alle verificaties uit

        sama new c32_user_auth → maakt bestand + template + .agent.md

        sama split → helpt bij Atomic splits

        sama verify-repo

    Pre-commit hooks + GitHub Action

    LSP / Editor integration (VS Code, Cursor, Windsurf)

    Claude / Cursor skill met automatische checks

Extra verbeteringen

    Monorepo support: Package-prefixen (pkg_auth_c32_...)

    Graduele adoptie: SAMA Light (alleen Sorted + Atomic) → Full SAMAX

    Frontend + Backend harmonisatie (vooral Next.js App Router)

    Deprecation policy: Duidelijke manier om oude lagen/bestanden af te bouwen

    Performance & Security gates in Atomic-check (bijv. flag grote N+1 queries)

Voorbeeld folder structuur (SAMA 2.0)

src/
├── c11_app.ts
├── features/
│   └── user/
│       ├── feat_user_c13_repo.ts
│       ├── feat_user_c31_types.ts
│       ├── feat_user_c32_auth.ts
│       ├── feat_user_c32_profile.ts
│       ├── feat_user_c40_service.ts
│       └── feat_user.agent.md
├── c60_stripe.ts
└── c70_auth_middleware.ts

Samenvatting: Waarom dit de gold standard wordt

    Behoudt mechanische verifieerbaarheid (grep + CLI)

    Wordt hybride (horizontaal + verticaal)

    Voegt documentatie als first-class citizen toe

    Wordt echt toolbaar en adopteerbaar

    Schaalt van solo-agent project tot middelgroot team

Dit is geen over-engineering — het lost precies de pijnpunten op die ontstaan als projecten groter worden dan 20-30k regels met agents.

Wil je dat ik een volledige officiële spec uitwerk (zoals de originele tdd.md pagina), inclusief verificatie commando’s en templates? Of focus op één deel (bijv. de CLI spec of een concrete Next.js template)?