aw-spec-cli 0.1.7 → 0.1.9

package/assets/guardrails/technology/dotnet-webapi/vertical-slices.md

@@ -0,0 +1,70 @@
+# Vertical Slice Standards
+
+> Pure technology (domain-agnostic) — domain additions in [[vertical-slices.domain]]. Commands: `/aw-spec-design`.
+
+## Feature organization
+
+- Each feature is a **self-contained vertical slice**: Command/Query, Handler, Endpoint,
+  Validator co-located in **one folder**.
+- No horizontal "Services/Managers" layers spanning slices.
+
+## Folder structure (per module)
+
+```
+<Module>/
+  Domain/
+    <Aggregate>.cs
+    <ChildEntity>.cs
+    <ValueObject>.cs
+    <Aggregate>Id.cs            [ValueObject<Guid>] partial struct
+    Events/                     DomainEventBase descendants
+    Specifications/
+  Persistence/<Aggregate>Configuration.cs
+  Features/<FeatureName>/       Command/Query + Handler + Endpoint + Validator
+  Interop/                      external-protocol adapters (see [[vertical-slices.domain]])
+  Shared/                       module-public DTOs + ToDto extensions
+```
+
+## Endpoint conventions
+
+- One endpoint **per file**. Endpoints inherit `SecureFastEndpoint<TRequest, TResponse>`.
+- Kebab-case routes; resources are plural nouns; verbs map to intent
+  (POST create, GET list/fetch, PUT full update, PATCH partial update, DELETE logical delete).
+- GUID route ids **MUST** use the `:guid` constraint.
+- Tagged via `Options(o => o.WithTags("NN - <Module> - (FastEndpoints)"))` and **MUST**
+  provide a `Summary`.
+- HTTP request classes are declared **inside the same file as the Endpoint** and contain
+  **primitive types only**.
+- Endpoints **MUST NOT** swallow exceptions — the central exception handler owns the contract.
+- See [[authorization]] for security cache policy on endpoints.
+
+## Validator placement
+
+- Validators live in the **feature folder** alongside the Command/Query they validate.
+- Validators check **request shape only**; aggregate invariants are enforced in the Domain.
+
+## DTO placement (immutable contracts)
+
+- DTOs live in `{Module}/Shared/` and are mapped with **hand-written** `ToDto()` /
+  `ToDtoList()` extension methods. AutoMapper-style reflection mappers are FORBIDDEN.
+- `record EntityDto { public required Guid Id { get; init; } ... }` — no setters;
+  required init for non-nullable members.
+- Every DTO **MUST** include a base64 `RowVersionBase64` when the aggregate implements
+  `IConcurrencyTracked`.
+- Paged results **MUST** use the standard `PagedResult<T>` shape
+  (`Items, TotalCount, PageNumber, PageSize`, computed `TotalPages`) with required init props.
+
+## Specification placement
+
+- Query composition lives in the **Domain**, under `{Module}/Domain/Specifications/`.
+  See [[persistence]] for specification rules.
+
+## Canonical example
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/vertical-slices.md`, mapped for `design`. The
+constitution set maps the rules without it.
+
+## Related
+
+- [[clean-architecture]] · [[cqrs]] · [[persistence]] · [[authorization]] · [[vertical-slices.domain]]

package/assets/guardrails/technology/dotnet-webapi/zero-trust.md

@@ -0,0 +1,48 @@
+# Zero-Trust Standards
+
+> Pure technology (domain-agnostic) — domain additions in [[zero-trust.domain]]. NON-NEGOTIABLE where marked. Commands: `/aw-spec-design`.
+
+## Transport security (mTLS / TLS)
+
+- HTTPS is enforced; **TLS 1.2 is the floor, TLS 1.3 the target**.
+- CORS uses **explicit allow-lists** — no wildcards.
+
+## Workload identity
+
+- Identity is composed via `.AddAppWeaverSecurity(...)` with an **external IdP**.
+- **Local identity stores are FORBIDDEN.**
+
+## Service authentication
+
+- Backing services and the IdP are declared as Aspire resources; connection strings,
+  hostnames, and ports are **discovered through Aspire — never hard-coded**.
+
+## Token propagation
+
+- Tokens / scopes are propagated through the request pipeline and honored on every endpoint
+  (see [[authorization]]).
+- Trace context propagates across `IMediator.Send`, `HttpClient`, and EF Core — bypassing the
+  framework `HttpClientFactory` is forbidden.
+
+## Internal authorization
+
+- Authorization is **role-based AND scope-based** — both enforced (see [[authorization]]).
+- Authentication tokens, password material, and private keys MUST NEVER appear in logs,
+  metrics, traces, or error messages (see [[data-classification]]).
+
+## Secrets
+
+- Secrets MUST come from **Aspire parameters** or a secrets manager (e.g. Azure Key Vault,
+  AWS Secrets Manager, HashiCorp Vault) — **NEVER from `appsettings.json`**.
+- Hard-coded connection strings, secrets, ports, or issuer URLs in source are a Forbidden
+  Pattern (see [[coding-standards]]).
+
+## Canonical example
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/zero-trust.md`, mapped for `design`. The
+constitution set maps the rules without it.
+
+## Related
+
+- [[authorization]] · [[auditing]] · [[data-classification]] · [[zero-trust.domain]]

package/assets/guardrails/technology/java-spring/README.md

@@ -0,0 +1,62 @@
+# java-spring — unauthored corpus
+
+This corpus is **empty on purpose**. It is the worked example of the kit's extension point:
+adding a technology means adding a folder here and mapping it from a project, and nothing else.
+No workflow, script, engine or schema change is involved, and no existing project is touched.
+
+Nothing in this folder is loaded by any command — a rule reaches a phase only by being listed in
+a project's `tech-rule-bindings.md`, and no shipped project lists anything here. (A Spring
+backend paired with the `nextjs` frontend lane is not left ungoverned by that: see below.) This file is the
+corpus index, in the same sense as [`../../README.md`](../../README.md); it is not a rule.
+
+## What already exists for a Spring lane
+
+One rule file for a Spring Boot backend is authored, and it does **not** live here — it lives
+in the corpus of the lane that reads it:
+[`../nextjs/api-integration.java-spring.md`](../nextjs/api-integration.java-spring.md), the
+cross-lane pairing rules for a `nextjs` frontend consuming a `java-spring` service. It is
+mapped from the frontend lane's `## /aw-spec-design-ui` and `## /aw-spec-implement-ui`
+headings through the `{{backend_stack}}` placeholder, so **it loads automatically the moment
+`.appweaver/stacks.json` declares a `java-spring` backend beside a `nextjs` frontend** — no
+project pack change, no workflow change.
+
+That file states what the UI may assume of a Spring service and where Spring's own defaults
+(0-based `Pageable`, `Page<T>` field names, `ProblemDetail`, `long` ids, `BigDecimal`,
+`LocalDateTime`, the `302`-to-login trap) will break the pairing if nothing was configured.
+It is written contract-first precisely because this corpus is unauthored: it defers to the
+service's published OpenAPI document rather than citing a rule file that does not exist yet.
+
+Authoring the service-side corpus below is what would let those rules be **enforced** at
+`design` and `implement` rather than only **expected** at `design-ui` and `implement-ui`.
+
+## Authoring it
+
+The corpus is keyed on the stack id `java-spring`, which is
+[`.appweaver/stack-profiles/java-spring.json`](../../../.appweaver/stack-profiles/java-spring.json)
+— the same id `select-stack` writes into `.appweaver/stacks.json` for a Spring Boot lane. Keep the
+folder name and the profile id the same word.
+
+Mirror the shape of [`../dotnet-webapi/`](../dotnet-webapi/), which is the reference corpus:
+
+| File | Role |
+|---|---|
+| `technology-constitution.md` | the ratified technology base — the one file `## /aw-spec-constitution` needs |
+| `<concern>.md` | one rule file per technical concern (architecture, persistence, testing, …) |
+| `examples/<concern>.md` | the worked `<SampleProjectName>` sample for the rule file beside it |
+
+Write the rules **domain-free**. A technology corpus is shared by every project that maps it, so a
+sentence about prescriptions or patients belongs in `guardrails/domain/<industry>/`, not here.
+The dotnet-webapi corpus holds zero domain words, and that is the property that let two packs
+collapse into one.
+
+There is no `technical-requirements.md` here: that file is the project owner's, and it lives in
+the project folder that maps this corpus.
+
+## Mapping it
+
+In a project's `tech-rule-bindings.md`, list the files under the command headings that should load
+them. A Spring Boot service project would start from
+[`../../projects/dotnet-default-project/tech-rule-bindings.md`](../../projects/dotnet-default-project/tech-rule-bindings.md)
+and repoint its `## /aw-spec-design`, `## /aw-spec-implement`, `## /aw-spec-build` and
+`## /aw-spec-constitution` bullets at `guardrails/technology/java-spring/…`. The domain map needs
+no edit at all — the domain is orthogonal to the stack, which is the whole point of the split.

package/assets/guardrails/technology/nextjs/accessibility-implementation.md

@@ -0,0 +1,56 @@
+# Accessibility Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE.
+> Commands: `/aw-spec-design-ui`, `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-I (accessibility floor).
+
+UX-I makes the floor non-negotiable; this file is what meeting it means in practice. The
+conformance TARGET arrives from the spec as a `UX-` Experience Standard — this file never
+restates it, and never lowers it.
+
+## What the design owns
+
+`design.ui.md` carries these, because they cannot be retrofitted:
+
+- **Focus placement** — where focus goes on navigation, on opening a dialog, on closing
+  one, and on a validation failure. Stated per interaction in `§4`.
+- **Keyboard reachability** — every interaction in `§4` is reachable and operable without
+  a pointer. An interaction with no keyboard path is a design defect.
+- **Announcement** — what assistive technology is told when a state changes: loading
+  finished, a row was removed, a submission failed. Silence is a decision, and it is
+  recorded as one.
+- **Semantics** — what each region and control MEANS, in `§3`'s responsibility column. The
+  element that carries it is `implement-ui`'s choice; the meaning is not.
+- **Alternatives** — the text alternative for every non-text element that carries
+  information, and the non-colour signal accompanying every colour-coded one.
+
+A `§6 Cross-Cutting` accessibility row with no `UX-` or `DA-n` citation is unanchored.
+
+## What implement-ui owns
+
+- Native semantic elements first. An ARIA role is a last resort and is justified in a
+  comment citing the design row it realises.
+- Every interactive element has an accessible name that matches its visible label.
+- Visible focus is never removed; a custom focus style meets the contrast floor.
+- Form fields are programmatically associated with their labels, their descriptions and
+  their error messages, and errors are announced when they appear.
+- Dialogs, menus and popovers trap focus while open and restore it on close.
+- Live regions are used for the state changes the design says are announced, and for no
+  others — an over-announcing surface is as unusable as a silent one.
+
+## Gates
+
+Per UX-XI, every interactive surface ships with an accessibility assertion in its test.
+An automated scan is a floor, not a pass: it cannot see focus order, announcement
+correctness or a meaningless accessible name. Disabling the accessibility linter inline is
+forbidden; a genuine exception is a time-boxed waiver recorded against the `UX-` id it
+relaxes.
+
+## Related
+
+- [[error-handling]] — the state changes that need announcing
+- [[design-system]] — contrast, focus styling and the non-colour signal, at the token layer
+- [[forms-and-validation]] — label association, error announcement, focus on failure
+- [[i18n]] — language declaration, so announcements are pronounced correctly
+- [[component-conventions]] — where the semantics land as code
+- [[frontend-testing]] — the assertion that keeps this from regressing

package/assets/guardrails/technology/nextjs/api-client.md

@@ -0,0 +1,56 @@
+# API Client Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE.
+> Commands: `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-IV (the contract is the only server input)
+> and UX-VII (mutations flow through one path).
+
+How `design.ui.md §5 Contract Binding` becomes code. `§5` is the lane boundary; this file
+is what keeps that boundary from leaking once there are real network calls.
+
+## One path in, one path out
+
+- Every request to the service goes through the lane's client layer in `lib/api/`. A raw
+  `fetch` anywhere else is forbidden — it is how a second, ungoverned contract appears.
+- Client types come from the service's published contract and are regenerated, never
+  patched. A hand-edit is lost on the next generation and lies until then.
+- Mutations go through one path (a Server Action or the generated client), always
+  revalidate what they invalidate, and declare their rollback where the design marked
+  them optimistic.
+
+## The boundary
+
+- The lane consumes the contract and NOTHING else from the service lane. It never assumes
+  a table, a handler, a persistence choice or an undocumented field.
+- An operation the experience needs and the contract does not offer is a CONTRACT DELTA
+  raised back to the service lane — never a workaround, never a second call composed to
+  fake it, and never a field derived client-side that the service should return.
+- Requests and responses are mapped at the boundary, not consumed raw through the UI. The
+  design's `§5` field shapes are what the mapping produces.
+
+## Failures
+
+- Every call maps its failure onto the `§4` state the design assigned it: retryable error,
+  user-fixable error, permission-denied, not-found. An unmapped failure is an unhandled
+  state.
+- A service error message is never surfaced verbatim — the user-facing text is the
+  design's, and the raw detail goes to telemetry with the `DC-` restrictions applied.
+- Retries happen only on operations the design marked safe to repeat.
+
+## Caching
+
+Per UX-VI, every fetch and route segment states its caching and revalidation policy
+explicitly. Serving stale content the contract marks authoritative is a correctness bug,
+not a performance trade-off.
+
+## Secrets
+
+Per UX-VIII, no credential, token or contract-restricted field enters client state,
+storage, the URL or telemetry. Server-only configuration stays server-only; a value that
+reaches the bundle is public.
+
+## Related
+
+- [[state-management]] — the cache these responses populate
+- [[error-handling]] — the states a failure produces
+- [[frontend-testing]] — contract-client integration tests against the generated types

package/assets/guardrails/technology/nextjs/api-integration.dotnet-webapi.md

@@ -0,0 +1,174 @@
+# API Integration — nextjs ⇄ dotnet-webapi
+
+> The CROSS-LANE pairing rules: how the `nextjs` frontend lane consumes an
+> `dotnet-webapi` service lane. NON-NEGOTIABLE where marked.
+> Commands: `/aw-spec-design-ui`, `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-IV (the contract is the only server input).
+
+This file is named for the service lane it pairs with, and a project maps it through the
+`{{backend_stack}}` placeholder — read from a Spring repo the same bullet resolves to
+`api-integration.java-spring.md`, and is reported missing rather than silently loading .NET
+assumptions into a Java project.
+
+**Every rule below has a source on the service side.** Where one is stated, the service rule
+file that owns it is cited. The UI never re-decides these; it consumes them, and a
+disagreement is a contract delta raised back to the service lane — never a client
+workaround.
+
+## The contract is the interface
+
+- **The service publishes a versioned OpenAPI document** and regenerates it cleanly in CI
+  (`dotnet-webapi/api-versioning`). That document — not a `.cs` file, not a route read off a
+  handler, not a field seen in a database — is the whole of what this lane may assume.
+- The typed client in `lib/api/` is GENERATED from that document and **never hand-edited**.
+  A patch is lost on the next generation and lies until then.
+- A field the UI needs that the document does not carry is a **contract delta**. It is
+  raised back to the service lane and recorded under `design.ui.md` §5 "Contract deltas
+  needed". Deriving it client-side, composing two calls to fake it, or reading it from a
+  second source are all forbidden.
+- The UI never assumes a table, an aggregate, a handler, a mediator message or a
+  persistence choice. Those are the service lane's internals
+  (`dotnet-webapi/clean-architecture`, `vertical-slices`).
+
+## Resource and verb semantics
+
+Routes follow the service's endpoint conventions (`dotnet-webapi/vertical-slices`), and the
+UI's expectations must match them exactly:
+
+| Verb | Service meaning | What the UI must do |
+|---|---|---|
+| `POST` | create | treat the response body as the authoritative created record, not the request echoed back |
+| `GET` | list or fetch | never rely on a side effect; a GET is safe to repeat |
+| `PUT` | **full** update | send the complete resource, not a patch — a missing field is a cleared field |
+| `PATCH` | partial update | send only changed fields |
+| `DELETE` | **logical** delete | never tell the user the record was permanently removed; the design's copy says what actually happened |
+
+- Routes are kebab-case with plural resource nouns; GUID route ids carry a `:guid`
+  constraint server-side, so an id the UI puts in a route must be a real GUID. A malformed
+  id is a client bug that surfaces as a routing failure, not a 404 to display as "not found".
+- **A logical delete is not a disappearance.** If the design's list still shows the record
+  in some state, the UI reflects that state; it does not optimistically remove the row
+  because the call returned 2xx.
+
+## Paged lists (NON-NEGOTIABLE)
+
+The service's list endpoints take `pageNumber` and `pageSize` and return the standard
+`PagedResult<T>` shape (`dotnet-webapi/vertical-slices`):
+
+```
+request  : ?pageNumber=<1-based>&pageSize=<n>
+response : { Items, TotalCount, PageNumber, PageSize, TotalPages }
+```
+
+- **`pageNumber` is 1-BASED.** A zero-based page index in client state is the single most
+  common integration defect against this service, and it silently skips or repeats the first
+  page rather than failing. The UI's paging state is 1-based end to end, or it converts at
+  the client boundary and nowhere else.
+- Paging, sorting and filtering are SERVER concerns. The UI never fetches everything and
+  pages in the browser — that breaks `TotalCount`, defeats the service's redaction, and
+  scales with the data rather than the screen.
+- `TotalPages` is computed by the service. The UI displays it; it does not recompute it and
+  risk disagreeing.
+- An empty `Items` with a non-zero `TotalCount` means the page is out of range — the design's
+  empty state distinguishes "no results" from "past the last page".
+
+## Optimistic concurrency (NON-NEGOTIABLE)
+
+The service is concurrency-tracked (`dotnet-webapi/api-versioning`, `persistence`):
+
+- Every read of a concurrency-tracked aggregate returns an **ETag** header, and its DTO
+  carries `RowVersionBase64`. **The UI keeps that token beside the record in client state.**
+  A record held without its token cannot be updated safely.
+- Update and delete send it back as **`If-Match`**. A request without `If-Match` on a
+  tracked aggregate is a lost-update waiting to happen.
+- Weak-validator prefixes (`W/`) are stripped on read; the token sent back is the strong
+  form.
+- A mismatch returns **`409 concurrency.conflict`**. That is a designed state, not a
+  transport error: it means someone else changed the record. The UI shows the design's
+  stale-record state and offers a reload — **it NEVER retries automatically**, because a
+  blind retry with a fresh token is exactly the overwrite the mechanism exists to prevent.
+- An optimistic UI update on a tracked aggregate declares its rollback and does not consider
+  the write settled until the response carries the new token.
+
+## Versioning
+
+- A breaking change to the service is a **versioned route prefix** (`v2/...`) and a MAJOR
+  bump (`dotnet-webapi/api-versioning`). The lane pins the version it generates against.
+- Moving to a new version means **regenerating the client**, not editing paths in place. The
+  move is a change recorded in the delta, and the design's §5 rows are re-checked against
+  the new document.
+- A superseded version stays available through its deprecation window — that window is the
+  lane's migration budget, not an invitation to stay behind indefinitely.
+
+## Errors
+
+The service's central exception handler owns the error contract; endpoints never swallow
+exceptions (`dotnet-webapi/vertical-slices`, `api-versioning`).
+
+- The UI maps failures by **status code and machine-readable error code** — never by
+  matching message text. Message text is not a contract and changes without a version bump.
+- A service error message is **never surfaced verbatim**. The user-facing text is the
+  design's; the raw detail goes to telemetry with the classification rules applied.
+- Each failure maps onto the state the design assigned it (`error-handling`):
+
+| From the service | Design state |
+|---|---|
+| `400` validation | field-level validation failure, focus moved to the first offending field |
+| `401` | session expired — re-authenticate, preserving the in-progress work where the design says so |
+| `403` | permission-denied, distinct from not-found and from error |
+| `404` | not-found for that route |
+| `409 concurrency.conflict` | stale record — reload, never auto-retry |
+| `5xx` / network | retryable error, and only on operations the design marked safe to repeat |
+
+## Authorization and redaction
+
+- Authorization is **role-based AND scope-based, both enforced server-side**
+  (`dotnet-webapi/authorization`). The client hides or disables an affordance; it never
+  becomes the authority. A route reachable by typing its address must still fail server-side.
+- **Field-level redaction happens in the service's projections**, by role and scope
+  (`dotnet-webapi/data-classification`). So the SAME endpoint legitimately returns a
+  different field set to different users. The UI treats an absent classified field as a
+  normal outcome — it renders the design's "not available to you" affordance, never an error
+  state, and never infers, caches or reconstructs the missing value.
+- `AllowAnonymous` exists only on infrastructure endpoints (`/.well-known`, `/health`,
+  `/alive`). Those are **not a data source** for the UI.
+
+## Caching
+
+- Mutating endpoints and sensitive-data reads are served `CachePolicy.NoStore`
+  (`dotnet-webapi/authorization`). The lane **must not** add its own cache in front of them:
+  no route-segment cache, no client-side memoisation that outlives the render, no service
+  worker entry.
+- Every other fetch and route segment **declares** its caching and revalidation policy
+  explicitly (UX-VI). A default that happens to work is not a policy.
+- Serving stale content the contract marks authoritative is a correctness bug, not a
+  performance trade-off.
+
+## Transport and origin
+
+- HTTPS only; the service enforces TLS 1.2 as a floor (`dotnet-webapi/zero-trust`).
+- **CORS is an explicit allow-list — no wildcards.** A new frontend origin is a service-side
+  configuration change, not something the client can route around. Where a call must be
+  same-origin, it goes through this lane's own server layer, which is a design decision
+  recorded in §5, not an ad-hoc proxy added during generation.
+- Every request carries the trace context so a UI action is followable through the service's
+  telemetry (`dotnet-webapi/auditing`). One HTTP layer means one consistent set of headers —
+  which is the other reason raw `fetch` outside `lib/api/` is forbidden.
+
+## Events are not a browser channel
+
+The service publishes domain events as **CloudEvents to a durable broker**, and downstream
+consumers build their own read models (`dotnet-webapi/eventing`).
+
+- **The browser is not a consumer.** This lane never subscribes to the broker, never reads
+  the OLTP store, and never treats an event contract as a UI contract.
+- Freshness comes from the invalidation policy the design states (`state-management`) —
+  refetch on mutation, revalidate on navigation, or a server-pushed channel the OpenAPI
+  document explicitly declares. "The event fired" is not something the UI can observe.
+
+## Related
+
+- [[api-client]] — the generated client layer these rules are realised in
+- [[auth-session]] — how the token is obtained and attached
+- [[error-handling]] — the states the failure table maps onto
+- [[state-management]] — where the ETag and the cached projection live