aw-spec-cli 0.1.4 → 0.1.6

package/assets/docs/VerticalSlice/unpack-reference-foundation.sh

@@ -1,218 +0,0 @@
-#!/usr/bin/env bash
-#
-# unpack-reference-foundation.sh — bash/macOS port of unpack-reference-foundation.ps1
-#
-# SYNOPSIS
-#   Unpack an AW-Spec reference pack file into a target project, renaming the
-#   sentinel app name to the caller's app name.
-#
-# DESCRIPTION
-#   Reads --pack-file (produced by pack-reference-foundation.sh/.ps1), takes the sentinel
-#   from its header (override with --sentinel), derives four case forms of the target app
-#   name, and writes every file block to --out-dir with the sentinel rewritten in both file
-#   CONTENTS and file/dir PATHS. Text blocks are rewritten and written as UTF-8; base64
-#   blocks are decoded as-is. Refuses to overwrite existing files unless --force.
-#
-# EXAMPLE
-#   ./unpack-reference-foundation.sh \
-#       --pack-file ./VerticalSlice.Reference.pack.txt \
-#       --target-app-name AppWeaver.Pharma \
-#       --out-dir ../../
-#
-set -euo pipefail
-
-# ------------------------------------------------------------------ defaults ---
-PACK_FILE=''
-TARGET_APP_NAME=''
-OUT_DIR='.'
-SENTINEL=''
-FORCE=0
-DRYRUN=0
-
-usage() {
-  cat >&2 <<'EOF'
-Usage: unpack-reference-foundation.sh --pack-file <file> --target-app-name <name>
-                                      [--out-dir <dir>] [--sentinel <name>]
-                                      [--force] [--dry-run]
-
-  -p, --pack-file <file>        Reference pack file to unpack               (required)
-  -t, --target-app-name <name>  New app name to rename the sentinel into    (required)
-  -o, --out-dir <dir>           Output root                   (default: .)
-      --sentinel <name>         Override the sentinel from the pack header
-      --force                   Overwrite files that already exist
-      --dry-run                 List what would be written, write nothing
-  -h, --help                    Show this help
-
-Positional fallback: unpack-reference-foundation.sh <pack-file> <target-app-name> [out-dir]
-EOF
-}
-
-# -------------------------------------------------------------- arg parsing ---
-while [ $# -gt 0 ]; do
-  case "$1" in
-    -p|--pack-file)        PACK_FILE="${2:?--pack-file needs a value}";             shift 2 ;;
-    -t|--target-app-name)  TARGET_APP_NAME="${2:?--target-app-name needs a value}"; shift 2 ;;
-    -o|--out-dir)          OUT_DIR="${2:?--out-dir needs a value}";                 shift 2 ;;
-    --sentinel)            SENTINEL="${2:?--sentinel needs a value}";               shift 2 ;;
-    --force)               FORCE=1; shift ;;
-    --dry-run)             DRYRUN=1; shift ;;
-    -h|--help)             usage; exit 0 ;;
-    --)                    shift; break ;;
-    -*)                    echo "Error: unknown option: $1" >&2; usage; exit 2 ;;
-    *)
-      if   [ -z "$PACK_FILE" ];       then PACK_FILE="$1"
-      elif [ -z "$TARGET_APP_NAME" ]; then TARGET_APP_NAME="$1"
-      else OUT_DIR="$1"
-      fi
-      shift ;;
-  esac
-done
-
-[ -n "$PACK_FILE" ]       || { echo "Error: --pack-file is required." >&2; usage; exit 2; }
-[ -n "$TARGET_APP_NAME" ] || { echo "Error: --target-app-name is required." >&2; usage; exit 2; }
-[ -f "$PACK_FILE" ]       || { echo "Error: pack file not found: $PACK_FILE" >&2; exit 1; }
-
-case "$TARGET_APP_NAME" in
-  *[!A-Za-z0-9._-]*)
-    echo "Error: --target-app-name may contain only letters, digits, '.', '_' or '-': $TARGET_APP_NAME" >&2
-    exit 2 ;;
-esac
-
-# ------------------------------------------------ sentinel from header --------
-if [ -z "$SENTINEL" ]; then
-  SENTINEL="$(LC_ALL=C sed -n 's/^#[[:space:]]*sentinel:[[:space:]]*\(.*[^[:space:]]\)[[:space:]]*$/\1/p' "$PACK_FILE" | head -n1)"
-fi
-[ -n "$SENTINEL" ] || { echo "Error: Sentinel not found in pack header; supply it with --sentinel." >&2; exit 1; }
-
-# ------------------------------------------------ derive case forms -----------
-to_lower() { printf '%s' "$1" | LC_ALL=C tr '[:upper:]' '[:lower:]'; }
-
-S_DOT="$SENTINEL";               T_DOT="$TARGET_APP_NAME"
-S_UND="${SENTINEL//./_}";        T_UND="${TARGET_APP_NAME//./_}"
-s_low="$(to_lower "$SENTINEL")"; t_low="$(to_lower "$TARGET_APP_NAME")"
-S_HYP="${s_low//./-}";           T_HYP="${t_low//./-}"
-S_LDOT="$s_low";                 T_LDOT="$t_low"
-
-FROM=(); TO=()
-add_form() {
-  local from="$1" to="$2" e
-  [ -n "$from" ] || return 0
-  [ "$from" = "$to" ] && return 0
-  if [ "${#FROM[@]}" -gt 0 ]; then
-    for e in "${FROM[@]}"; do [ "$e" = "$from" ] && return 0; done
-  fi
-  FROM+=("$from"); TO+=("$to")
-}
-add_form "$S_DOT"  "$T_DOT"
-add_form "$S_UND"  "$T_UND"
-add_form "$S_HYP"  "$T_HYP"
-add_form "$S_LDOT" "$T_LDOT"
-
-# Sort indices by FROM length descending
-ORDER=()
-{
-  local_n="${#FROM[@]}"
-  used=(); for ((k = 0; k < local_n; k++)); do used[$k]=0; done
-  for ((pass = 0; pass < local_n; pass++)); do
-    best=-1; bestlen=-1
-    for ((j = 0; j < local_n; j++)); do
-      if [ "${used[$j]}" -eq 0 ] && [ "${#FROM[$j]}" -gt "$bestlen" ]; then
-        bestlen="${#FROM[$j]}"; best="$j"
-      fi
-    done
-    used[$best]=1; ORDER+=("$best")
-  done
-}
-
-REPL_OUT=''
-apply_repl() {
-  local text="$1" idx from to
-  if [ "${#ORDER[@]}" -gt 0 ]; then
-    for idx in "${ORDER[@]}"; do
-      from="${FROM[$idx]}"; to="${TO[$idx]}"
-      text="${text//"$from"/$to}"
-    done
-  fi
-  REPL_OUT="$text"
-}
-
-# ------------------------------------------------ output root ----------------
-[ -d "$OUT_DIR" ] || mkdir -p "$OUT_DIR"
-OUT_ROOT="$(cd "$OUT_DIR" && pwd -P)"
-
-# ------------------------------------------------ base64 decoder (portable) --
-B64D=()
-if   printf 'aGk=' | base64 -d        >/dev/null 2>&1; then B64D=(base64 -d)
-elif printf 'aGk=' | base64 -D        >/dev/null 2>&1; then B64D=(base64 -D)
-elif printf 'aGk=' | base64 --decode  >/dev/null 2>&1; then B64D=(base64 --decode)
-else                                                        B64D=(openssl base64 -d -A)
-fi
-
-# ------------------------------------------------ parse file blocks ----------
-rels=(); encs=(); contents=()
-in_block=0; cur_rel=''; cur_enc=''; cur_content=''; first_line=1
-file_re='^<<<FILE path="([^"]+)"( encoding="([^"]+)")?>>>[[:space:]]*$'
-
-while IFS= read -r line || [ -n "$line" ]; do
-  line="${line%$'\r'}"
-  if [ "$in_block" -eq 0 ]; then
-    if [[ "$line" =~ $file_re ]]; then
-      cur_rel="${BASH_REMATCH[1]}"
-      cur_enc="${BASH_REMATCH[3]:-}"
-      in_block=1; first_line=1; cur_content=''
-    fi
-  else
-    if [ "$line" = '<<<ENDFILE>>>' ]; then
-      rels+=("$cur_rel"); encs+=("$cur_enc"); contents+=("$cur_content")
-      in_block=0
-    elif [ "$first_line" -eq 1 ]; then
-      cur_content="$line"; first_line=0
-    else
-      cur_content="$cur_content"$'\n'"$line"
-    fi
-  fi
-done < "$PACK_FILE"
-
-[ "${#rels[@]}" -gt 0 ] || { echo "Error: No <<<FILE>>> blocks found in pack: $PACK_FILE" >&2; exit 1; }
-
-# ------------------------------------------------ resolve destinations -------
-dests=()
-for ((i = 0; i < ${#rels[@]}; i++)); do
-  apply_repl "${rels[$i]}"
-  dests+=("$OUT_ROOT/$REPL_OUT")
-done
-
-# ------------------------------------------------ conflict guard -------------
-if [ "$FORCE" -eq 0 ] && [ "$DRYRUN" -eq 0 ]; then
-  conflicts=()
-  for d in "${dests[@]}"; do [ -e "$d" ] && conflicts+=("$d"); done
-  if [ "${#conflicts[@]}" -gt 0 ]; then
-    echo "Error: Refusing to overwrite existing files (re-run with --force):" >&2
-    printf '  %s\n' "${conflicts[@]}" >&2
-    exit 1
-  fi
-fi
-
-# ------------------------------------------------ write ----------------------
-written=0
-for ((i = 0; i < ${#rels[@]}; i++)); do
-  rel="${rels[$i]}"; enc="${encs[$i]}"; dest="${dests[$i]}"
-  if [ "$DRYRUN" -eq 1 ]; then
-    echo "WOULD WRITE  $rel  ->  $dest"
-    continue
-  fi
-  mkdir -p "$(dirname "$dest")"
-  if [ "$enc" = 'base64' ]; then
-    printf '%s' "${contents[$i]}" | tr -d '[:space:]' | "${B64D[@]}" > "$dest"
-  else
-    apply_repl "${contents[$i]}"
-    printf '%s' "$REPL_OUT" > "$dest"
-  fi
-  written=$((written + 1))
-done
-
-if [ "$DRYRUN" -eq 1 ]; then
-  echo "DryRun: ${#rels[@]} file(s) would be written to $OUT_ROOT (sentinel '$SENTINEL' -> '$TARGET_APP_NAME')."
-else
-  echo "Unpacked $written file(s) to $OUT_ROOT (sentinel '$SENTINEL' -> '$TARGET_APP_NAME')."
-fi

package/assets/docs/architecture/clean-architecture.md

@@ -1,71 +0,0 @@
-# Clean Architecture Standards
-
-> Pure technology (domain-agnostic). NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Dependency direction
-
-Dependencies flow **inward only**:
-
-```
-API  ->  Application (Features)  ->  Domain  <-  Infrastructure
-```
-
-The Domain is the innermost ring; everything depends on it and it depends on nothing.
-
-## Layer responsibilities
-
-- **API** — HTTP surface (FastEndpoints). Translates transport to/from mediator
-  messages. MUST NOT contain business logic.
-- **Application (Features)** — Command/Query handlers, validators, orchestration.
-  Dispatched via `IMediator`. MUST NOT depend on API frameworks or concrete EF Core types.
-- **Domain** — aggregates, entities, value objects, domain events, specifications.
-  Framework-agnostic.
-- **Infrastructure** — EF Core, external service clients, persistence configuration.
-  Depends inward on Domain abstractions.
-
-## Allowed dependencies / annotations in Domain
-
-The Domain layer is framework-agnostic. The **only** allowed annotations are:
-
-- `[NotMapped]`
-- `[ValueObject<T>]` (Vogen)
-- `System.ComponentModel.DataAnnotations.Schema`
-
-## Infrastructure boundaries
-
-- EF Core mapping lives **only** in `{Module}/Persistence/<Aggregate>Configuration.cs` and is
-  applied via `ApplyConfigurationsFromAssembly`.
-- **Endpoints MUST NOT** call repositories, `DbContext`, or `IUnitOfWork` directly; they
-  **MUST** call `IMediator.Send(...)`.
-- **Application Features MUST NOT** depend on API frameworks or concrete EF Core types.
-- Direct `DbContext` access from Endpoints or Application Features (outside the
-  repository / specification surface) is FORBIDDEN.
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-The dependency rule in practice — the **API** layer depends inward via `IMediator` only
-(never `IRepository`/`DbContext`); the **Application** layer depends on Domain abstractions
-(`IRepository<Project>`), never on concrete EF Core types:
-
-```csharp
-// API layer — <SampleProjectName>.Service/Projects/Features/CreateProject/CreateProjectEndpoint.cs
-public class CreateProjectEndpoint(IMediator _mediator)
-    : SecureFastEndpoint<CreateProjectRequest, ProjectDto>
-{
-    protected override Task<Result<ProjectDto>> ExecuteAsync(
-        CreateProjectRequest req, CancellationToken ct)
-        => _mediator.Send(new CreateProjectCommand(
-            req.Code, req.Name, req.Description, req.StartDate, req.EndDate, req.OwnerId), ct);
-}
-
-// Application layer — depends on Domain abstractions, not EF Core
-public class CreateProjectCommandHandler(
-    IRepository<Project> _repo, IUnitOfWork _uow, IPublisher _eventBus)
-    : ICommandHandler<CreateProjectCommand, Result<ProjectDto>> { /* ... */ }
-```
-
-## Related
-
-- [[cqrs]] — how the Application layer dispatches work
-- [[persistence]] — repository + specification surface, EF Core conventions
-- [[vertical-slices]] — physical organization of the layers per feature

package/assets/docs/architecture/cqrs.md

@@ -1,141 +0,0 @@
-# CQRS + Mediator Standards
-
-> Pure technology (domain-agnostic) — domain additions in [[cqrs.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Command / query patterns
-
-- All application logic is dispatched through **`AppWeaver.Mediator`** (NOT MediatR).
-- **Commands:** `record XxxCommand(...) : ICommand<Result<TDto>>` or `ICommand<Result>`.
-- **Queries:** `record XxxQuery(...) : IQuery<Result<TDto>>`.
-- Handlers use **primary-constructor DI** and return `ValueTask<Result<T>>`.
-
-## Mediator conventions
-
-- Endpoints call `IMediator.Send(...)` — never repositories/`DbContext`/`IUnitOfWork` directly.
-- Raw `Guid` parameters at the Application boundary **MUST be wrapped** into strongly-typed
-  IDs at the handler edge.
-
-## Pipeline behaviors
-
-Enabled at startup, in order:
-
-1. Logging behavior
-2. FluentValidation behavior
-
-> Additional cross-cutting behaviors (e.g. domain access-audit behaviors) may be appended —
-> see [[cqrs.domain]] for the domain audit-pipeline behavior.
-
-## Result pattern
-
-- Errors are returned as `Result<T>.Failure(new Error(code, message, status, resource))`.
-- **Exceptions MUST NOT** be used for expected business outcomes (validation, not-found,
-  conflict, concurrency). `DomainException` is reserved for invariant violations and is
-  caught by the centralized exception handler.
-- **Error code** MUST be a stable dot-namespaced slug — e.g. `resource.not_found`,
-  `concurrency.conflict`, `resource.duplicate`.
-- **resource** MUST be the kebab-case resource name.
-
-## Handler responsibilities
-
-- **Read handlers** inject `IReadRepository<TAggregate>`.
-- **Write handlers** inject `IRepository<TAggregate>` + `IUnitOfWork` (+ `IPublisher`
-  when domain events are produced).
-- Validators check **request shape only**; invariants are enforced inside the aggregate.
-- No business logic in handlers (anemic-domain anti-pattern — see [[domain-driven-design]]).
-
-## Transaction handling
-
-- Write handlers **MUST** wrap mutating work in
-  `IUnitOfWork.ExecuteInTransactionAsync(..., IsolationLevel.ReadCommitted, ct)` and call
-  `SaveChangesAsync` **inside** the lambda.
-- They **MUST** publish domain events and call `ClearDomainEvents()` before returning.
-- **One command mutates one aggregate per transaction** — cross-aggregate effects flow
-  through domain events or follow-up commands (see [[eventing]]).
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-Command as a `record`, write handler with transaction + event publication, and a read handler
-returning `Result.Failure(...)` for the expected not-found outcome (no exceptions):
-
-```csharp
-// Command — record implementing ICommand<Result<TDto>>
-public record CreateProjectCommand(
-    string Code, string Name, string? Description,
-    DateOnly StartDate, DateOnly? EndDate, Guid? OwnerId
-) : ICommand<Result<ProjectDto>>;
-
-// Write handler — primary-ctor DI, transaction, publish + clear events, Result<T>
-public class CreateProjectCommandHandler(
-    IRepository<Project> _repo, IUnitOfWork _uow, IPublisher _eventBus
-) : ICommandHandler<CreateProjectCommand, Result<ProjectDto>>
-{
-    public async ValueTask<Result<ProjectDto>> Handle(
-        CreateProjectCommand request, CancellationToken ct)
-        => await _uow.ExecuteInTransactionAsync(async () =>
-        {
-            var ownerId = request.OwnerId.HasValue
-                ? TaskUserId.From(request.OwnerId.Value) : (TaskUserId?)null;
-            var entity = new Project(request.Code, request.Name, request.StartDate, ownerId);
-
-            await _repo.AddAsync(entity, ct);
-            await _uow.SaveChangesAsync(ct);
-
-            foreach (var e in entity.DomainEvents) await _eventBus.Publish(e, ct);
-            entity.ClearDomainEvents();
-
-            return Result<ProjectDto>.Ok(entity.ToDto());
-        }, IsolationLevel.ReadCommitted, ct);
-}
-
-// Read handler — IReadRepository + Specification; not-found is a Result, not an exception
-public class GetProjectByIdQueryHandler(IReadRepository<Project> _repo)
-    : IQueryHandler<GetProjectByIdQuery, Result<ProjectDto>>
-{
-    public async ValueTask<Result<ProjectDto>> Handle(
-        GetProjectByIdQuery request, CancellationToken ct)
-    {
-        Guard.NotDefault(request.Id, nameof(request.Id));
-        var entity = await _repo.FirstOrDefaultAsync(
-            new ProjectWithTasksSpec(ProjectId.From(request.Id)), ct);
-
-        return entity is null
-            ? Result<ProjectDto>.Failure(new Error(
-                "project.not_found", $"Project {request.Id} not found", 404, "projects"))
-            : Result<ProjectDto>.Ok(entity.ToDto());
-    }
-}
-```
-
-Commands with no return payload use `ICommand<Result>` (e.g. delete) and return
-`Result.Success()` / `Result.Failure(...)`:
-
-```csharp
-public record DeleteProjectCommand(Guid Id, string RowVersionBase64) : ICommand<Result>;
-
-public class DeleteProjectCommandHandler(IRepository<Project> _repo, IUnitOfWork _uow, IPublisher _bus)
-    : ICommandHandler<DeleteProjectCommand, Result> { /* ... returns Result.Success() */ }
-```
-
-Composition — register the mediator with the logging + validation pipeline behaviors,
-the validators, and the in-process event bus (one-time startup wiring):
-
-```csharp
-// <SampleProjectName>.Service/Extensions/ApplicationServiceRegistration.cs
-services.AddMediator(builder =>
-{
-    builder.UseDefault()
-           .UseBehaviors()
-           .AddLoggingBehavior()
-           .AddFluentValidationBehavior();          // domain projects also add PHI-audit — see [[cqrs.domain]]
-}, options => options.Provider = "Default");
-
-services.AddAppWeaverMediatorHandlersFrom(typeof(ApplicationServiceRegistration));
-services.AddValidatorsFromAssembly(typeof(ApplicationServiceRegistration).Assembly);
-
-services.AddEventBus(b => b.UseDefaultEventBus(o =>
-    o.RegisterServicesFromAssembly(typeof(ApplicationServiceRegistration).Assembly)));
-```
-
-## Related
-
-- [[clean-architecture]] · [[persistence]] · [[eventing]] · [[domain-driven-design]] · [[cqrs.domain]]

package/assets/docs/architecture/eventing.md

@@ -1,83 +0,0 @@
-# Eventing Standards
-
-> Pure technology (domain-agnostic) — domain additions in [[eventing.domain]]. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Domain events
-
-- Domain Events derive from `DomainEventBase`, are **immutable**, and are added **inside**
-  aggregate methods via `AddDomainEvent(...)`.
-- They are published **explicitly** by command handlers: `foreach` over `entity.DomainEvents`,
-  then `ClearDomainEvents()` before returning. See [[cqrs]].
-- Cross-aggregate effects flow through domain events or follow-up commands — never a
-  multi-aggregate transaction.
-
-## CloudEvents conventions
-
-- Asynchronous propagation of domain events to downstream consumers uses a **durable event
-  stream**: **CloudEvents** over the configured broker (e.g. Azure Service Bus, AWS SQS/SNS,
-  or RabbitMQ).
-- Each module owns its **public events**; downstream consumers subscribe to them rather than
-  reading the OLTP database.
-
-## Event immutability
-
-- Published events are immutable facts. Consumers build their own read models; they
-  **MUST NOT** query the source OLTP database directly.
-- Analytics / reporting is built from emitted events — **never** by querying the OLTP DB
-  directly.
-
-## Event versioning
-
-- The service publishes a versioned, machine-readable **AsyncAPI** document for event
-  contracts.
-- Breaking changes to a domain-event contract are **MAJOR** version bumps and require the
-  AsyncAPI document to regenerate cleanly (CI gate). See [[api-versioning]].
-
-## Broker integration patterns
-
-- The message broker is declared as an Aspire resource and referenced via `.WithReference(...)`;
-  connection details are discovered through Aspire, never hard-coded.
-- Trace context **MUST** propagate across `IMediator.Send`, `HttpClient`, and EF Core; bypassing
-  the framework's `HttpClientFactory` is forbidden.
-  (Outbound domain-protocol propagation is covered in [[eventing.domain]].)
-
-## Inbound integration rule (generic)
-
-- Inbound integrations flow through **Interop adapters** that translate to internal commands;
-  they **MUST NOT** write directly to aggregates. (Domain feed types in [[eventing.domain]].)
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-Immutable domain event, raised inside the aggregate, published explicitly by the handler:
-
-```csharp
-// <SampleProjectName>.Service/Projects/Domain/Events/ProjectCreatedEvent.cs
-public class ProjectCreatedEvent(Guid projectId, string code, string name) : DomainEventBase
-{
-    public Guid ProjectId { get; } = projectId;   // get-only — immutable
-    public string Code { get; } = code;
-    public string Name { get; } = name;
-}
-```
-
-```csharp
-// Raised inside the aggregate method (never in the handler):
-AddDomainEvent(new ProjectCreatedEvent(Id.Value, Code.Value, Name));
-
-// Published by the command handler after SaveChanges, then cleared:
-foreach (var domainEvent in entity.DomainEvents)
-    await _eventBus.Publish(domainEvent, ct);   // IPublisher — in-process today, broker tomorrow
-entity.ClearDomainEvents();
-```
-
-Composition — register the event bus (handlers discovered from the assembly):
-
-```csharp
-// <SampleProjectName>.Service/Extensions/ApplicationServiceRegistration.cs
-services.AddEventBus(b => b.UseDefaultEventBus(o =>
-    o.RegisterServicesFromAssembly(typeof(ApplicationServiceRegistration).Assembly)));
-```
-
-## Related
-
-- [[cqrs]] · [[modular-monolith]] · [[api-versioning]] · [[eventing.domain]]

package/assets/docs/architecture/folder-structure.md

@@ -1,61 +0,0 @@
-# Mandatory Folder Structure
-
-> Pure technology (domain-agnostic) — domain additions (Interop adapters, conformance tests, fixtures) in [[folder-structure.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
->
-> Replace `<SampleProjectName>` with the project name (e.g. `Acme.Billing`).
-
-## Layout
-
-```
-src/
-  <SampleProjectName>.AppHost/            Aspire composition root (Program.cs)
-  <SampleProjectName>.ServiceDefaults/    OTel + Serilog + resilience + service discovery
-  <SampleProjectName>.Service/            headless API runtime  (a.k.a. <SampleProjectName>.Api)
-    Program.cs                            composition only
-    GlobalUsings.cs
-    appsettings.json / appsettings.{Env}.json
-    Common/                               PagedResult<T> + shared value objects
-    Extensions/                           ApplicationServiceRegistration (mediator/eventbus),
-                                          InfrastructureServiceRegistration (DbContext/repos),
-                                          Aspire/Host extensions, SpecificationExtensions
-    Infrastructure/
-      ApplicationDbContext.cs             ContextAwareDbContext<T>
-      *DbContextFactory.cs                design-time factories
-      Migrations/
-    Utilities/                            ETag/HTTP helpers (HttpRequest/Response ETag ext)
-    <Module>/                             one folder per bounded context
-      Domain/
-        <Aggregate>.cs
-        <ChildEntity>.cs
-        <ValueObject>.cs
-        <Aggregate>Id.cs                  [ValueObject<Guid>] partial struct
-        Enums/                            (optional) status/priority enums
-        Events/                           DomainEventBase descendants
-        Specifications/                   Specification<TAggregate>
-      Persistence/
-        <Aggregate>Configuration.cs       (+ <ChildEntity>Configuration.cs)
-      Features/<FeatureName>/             Command/Query + Handler + Endpoint + Validator
-      Shared/                             module-public DTOs + ToDto mapping extensions
-tests/
-  <SampleProjectName>.UnitTests/
-  <SampleProjectName>.IntegrationTests/   Testcontainers-driven
-  <SampleProjectName>.TestFixtures/       shared test fixtures
-helm/
-  <SampleProjectName>.Api/
-docs/                                     engineering standards (see [[README]] + context map)
-```
-
-## Rules
-
-- Each **module** is a top-level folder with `Domain / Features / Persistence / Shared`
-  (see [[modular-monolith]], [[vertical-slices]]).
-- Each **feature** is a self-contained vertical slice (Command/Query + Handler + Endpoint +
-  Validator co-located).
-- Cross-cutting files (`Program.cs`, `GlobalUsings.cs`, `Directory.Build.props`,
-  `Directory.Packages.props`, `global.json`) MUST stay at the level they occupy in the
-  AppWeaver template.
-- New folders outside this structure require a constitution amendment.
-
-## Related
-
-- [[modular-monolith]] · [[vertical-slices]] · [[clean-architecture]] · [[folder-structure.domain]]

package/assets/docs/architecture/modular-monolith.md

@@ -1,47 +0,0 @@
-# Modular Monolith Standards
-
-> Pure technology (domain-agnostic). NON-NEGOTIABLE where marked. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Module boundaries
-
-- The runtime is a **single deployable service** partitioned into bounded contexts (modules).
-- Each module is a **top-level folder** containing four mandatory child folders:
-  `Domain`, `Features`, `Persistence`, `Shared` (plus `Interop` where applicable).
-- A module **owns** its aggregates, persistence configurations, DTOs, integration
-  adapters/projectors, and public events. Nothing outside the module may reach past these.
-
-## Cross-module communication
-
-- Modules **MUST NOT** reference another module's `Domain` types except through
-  **strongly-typed IDs** or the other module's **`Shared` DTOs**.
-- Modules **MUST NOT** take EF Core `DbSet` dependencies on entities they do not own.
-- **Cross-module reads** go through the other module's `Shared` DTOs or its `IMediator`
-  queries — never through its `DbContext` entities.
-- **Cross-module writes** go through commands published to `IMediator` (in-process today,
-  on the event bus tomorrow). A module **MUST NOT** acquire a write lock on another
-  module's aggregate.
-- No horizontal "Services/Managers" layers across slices.
-
-## Schema-per-module guidance
-
-- Per-module schemas in PostgreSQL (**schema-per-module**) are RECOMMENDED so a future
-  service extraction is a clean cutover.
-
-## Module isolation / testability
-
-- Every module **MUST be testable in isolation**: its unit tests and handler tests
-  **MUST NOT** require any other module to be loaded.
-
-## Future microservice extraction strategy
-
-- Today's modules are tomorrow's services. Splitting a module into its own service
-  **MUST require zero changes to the domain code of other modules**.
-- Migration to microservices is **approved by amendment** when a module's deployment
-  cadence, scaling profile, team ownership, or regulatory boundary materially diverges
-  from the rest of the monolith.
-
-## Related
-
-- [[vertical-slices]] — feature organization within a module
-- [[clean-architecture]] — dependency rule across layers
-- [[eventing]] — async cross-module/event-bus propagation