aw-spec-cli 0.1.4 → 0.1.6

package/assets/docs/security/authorization.md

@@ -1,87 +0,0 @@
-# Authorization Standards
-
-> Pure technology (domain-agnostic) — domain roles & matrix in [[authorization.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## Authorization model
-
-- Authorization is **role-based AND scope-based** — both MUST pass.
-- Per-route authorization is declared per endpoint via `Roles(...)` + scope evaluation,
-  documented in an authorization matrix.
-- Identity comes from an external IdP via `.AddAppWeaverSecurity(...)` — local identity stores
-  forbidden (see [[zero-trust]]).
-- (The concrete role set and scope syntax are domain-specific — see [[authorization.domain]].)
-
-## Policy evaluation
-
-- Endpoints inherit `SecureFastEndpoint<TRequest, TResponse>` and MUST override
-  `GetSecurityCachePolicy()` to declare `SecurityLevel` and `CachePolicy`.
-  - Mutating endpoints MUST use `CachePolicy.NoStore`.
-  - Sensitive-data read endpoints MUST use `CachePolicy.NoStore`.
-- Field-level redaction (minimum-necessary) lives in **projection extensions**, not
-  controllers (see [[data-classification]]; domain specifics in [[authorization.domain]]).
-
-## Endpoint authorization patterns
-
-- `AllowAnonymous()` is permitted **only** for infrastructure/discovery endpoints
-  (`/.well-known`, `/health`, `/alive`, service metadata) and during initial scaffolding
-  before merge to a protected branch.
-- `AllowAnonymous()` on sensitive-data or mutating endpoints in any CI-protected branch is a
-  Forbidden Pattern (CI grep gate; see [[coding-standards]]).
-
-## Canonical example (agent reference — `<SampleProjectName>` sample)
-
-Secure endpoint — declare auth scheme + roles in `Configure()`, and the security/cache policy
-in `GetSecurityCachePolicy()`:
-
-```csharp
-public override void Configure()
-{
-    Post("/projects");
-    AuthSchemes("Bearer");        // JWT from the external IdP
-    Roles("Admin");               // role-based gate (combine with scope checks for FHIR — see .domain)
-    Summary(s => s.Summary = "Create a new project");
-    Options(o => o.WithTags("02 - Project - (FastEndpoints)"));
-}
-
-protected override SecurityCachePolicy GetSecurityCachePolicy() => new()
-{
-    SecurityLevel = SecurityLevel.Internal,   // Internal | Restricted (admin/sensitive)
-    CachePolicy   = CachePolicy.NoStore       // NoStore for mutating/sensitive; PrivateCache for cacheable reads
-};
-```
-
-> Mutating endpoints use `CachePolicy.NoStore`. Admin/audit endpoints (e.g. list-including-deleted)
-> use `SecurityLevel.Restricted`. `AllowAnonymous()` is only for infrastructure/discovery routes
-> or pre-merge scaffolding (the template ships endpoints scaffolded with `AllowAnonymous()` and
-> the `AuthSchemes`/`Roles` lines commented — replace them before merging to a protected branch).
-
-Composition — external IdP only (no local identity store), role-based authorization:
-
-```csharp
-// <SampleProjectName>.Service/Program.cs
-builder.Services.AddAppWeaverSecurity(security =>
-{
-    security
-        .AddAuthentication(auth =>
-        {
-            if (authProvider == "EntraExternalID")
-                auth.UseEntraExternalID(o => { o.TenantId = cfg["EntraExternalID:TenantId"]!;
-                                               o.ClientId = cfg["EntraExternalID:ClientId"]!; }, cfg);
-            else
-                auth.UseAzureAdB2C(o => { o.Domain = cfg["AzureAdB2C:Domain"]!;
-                                          o.ClientId = cfg["AzureAdB2C:ClientId"]!;
-                                          o.SignUpSignInPolicyId = cfg["AzureAdB2C:SignUpSignInPolicyId"]!; }, cfg);
-        })
-        .AddAuthorization(authz => authz.UseRoleBased(o => o.AdminRole = "Admin"));
-        // NOTE: no .AddIdentity(...) — the IdP is the source of truth (see [[zero-trust]])
-}, options => { }, configuration: cfg);
-
-// ... pipeline order ...
-app.UseAuthentication();
-app.UseAuthorization();
-app.UseFastEndpoints();
-```
-
-## Related
-
-- [[zero-trust]] · [[auditing]] · [[data-classification]] · [[authorization.domain]]

package/assets/docs/security/data-classification.md

@@ -1,38 +0,0 @@
-# Data Classification Standards
-
-> Pure technology (domain-agnostic) — domain data categories in [[data-classification.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-specify`, `/aw-spec-plan`, `/aw-spec-implement`.
-
-## Classification framework
-
-- Every data element is assigned a **sensitivity class**; controls (encryption, masking,
-  logging, export) are applied per class.
-- The concrete sensitivity taxonomy is project/domain-specific — see
-  [[data-classification.domain]] for the domain taxonomy.
-
-## Masking rules
-
-- Field-level redaction is applied in **projection extensions**, not controllers
-  (minimum-necessary by role/scope — see [[authorization]]).
-
-## Encryption requirements
-
-- AES-256 at rest (DB TDE + customer-managed key); TLS 1.2+ in transit (1.3 target);
-  encrypted backups.
-- **Application-level field encryption** for the most sensitive fields (the concrete field
-  list is domain-specific — see [[data-classification.domain]]).
-
-## Logging restrictions
-
-- **NEVER** log or emit in metrics/traces: authentication tokens, password material, private
-  keys, or full payment-card data.
-  (Domain-sensitive elements — PHI, SSN, government IDs — see [[data-classification.domain]].)
-
-## Export restrictions
-
-- Production data MUST NOT be copied to non-production environments without an approved
-  de-identification / anonymization step.
-- (Domain de-identification / anonymization specifics — see [[data-classification.domain]].)
-
-## Related
-
-- [[auditing]] · [[authorization]] · [[zero-trust]] · [[data-classification.domain]]

package/assets/docs/security/zero-trust.md

@@ -1,76 +0,0 @@
-# Zero-Trust Standards
-
-> Pure technology (domain-agnostic) — domain additions in [[zero-trust.domain]]. NON-NEGOTIABLE where marked. Commands: `/aw-spec-plan`, `/aw-spec-implement`.
-
-## 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 (agent reference — `<SampleProjectName>` sample)
-
-Secrets/IdP config read from configuration (Aspire parameters / secrets manager) — never
-hard-coded; explicit CORS allow-list; HTTPS enforced outside development:
-
-```csharp
-// <SampleProjectName>.Service/Program.cs
-var cfg = builder.Configuration;
-
-// IdP settings come from config — no client secrets or issuer URLs in source (see [[authorization]])
-builder.Services.AddAppWeaverSecurity(security => security
-    .AddAuthentication(auth => auth.UseAzureAdB2C(o =>
-    {
-        o.Instance = cfg["AzureAdB2C:Instance"]!;
-        o.Domain   = cfg["AzureAdB2C:Domain"]!;
-        o.ClientId = cfg["AzureAdB2C:ClientId"]!;
-    }, cfg))
-    .AddAuthorization(authz => authz.UseRoleBased(o => o.AdminRole = "Admin")),
-    options => { }, configuration: cfg);
-
-// Explicit CORS allow-list — no wildcards
-builder.Services.AddCors(o => o.AddPolicy("DevelopmentPolicy", p => p
-    .WithOrigins("http://localhost:7000", "http://localhost:3000")
-    .AllowAnyMethod().AllowAnyHeader().AllowCredentials()));
-
-var app = builder.Build();
-app.UseCors("DevelopmentPolicy");
-app.UseAuthentication();
-app.UseAuthorization();
-
-if (!app.Environment.IsEnvironment("Development"))
-    app.UseHttpsRedirection();   // enforce HTTPS outside dev
-```
-
-## Related
-
-- [[authorization]] · [[auditing]] · [[data-classification]] · [[zero-trust.domain]]

package/assets/docs/technology-constitution.md

@@ -1,172 +0,0 @@
-# Technology Constitution (domain-agnostic base)
-
-> **AppWeaver template — reusable engineering constitution.**
-> This file holds the technology-only principles. It is **not ratified on its own** — it is
-> composed with exactly **one** domain addenda file at ratification time.
-
-## How to use (compose-at-ratification)
-
-This file is **auto-loaded** by `/aw-spec-constitution` (it is in that command's auto-loaded
-engineering-standards set). You therefore pass only the **domain addenda**, which composes on
-top of this base:
-
-```
-/aw-spec-constitution @docs/healthcare-constitution.md
-/aw-spec-constitution @docs/pharma-constitution.md
-```
-
-`/aw-spec-constitution` merges the auto-loaded technology base with the supplied domain addenda
-into the single ratified `.aw-spec/memory/constitution.md` (auto-loaded by every command
-thereafter). Passing `@docs/technology-constitution.md` explicitly is harmless but redundant.
-
-- Core Principles **I–XV** below are domain-agnostic and reused verbatim across every project.
-- **PROJECT IDENTITY**, **REGULATORY REGIME**, domain principles (**XVI+**), folder additions,
-  and governance-override values are **supplied by the domain addenda file** — do not fill them
-  here.
-- Paths below use this repo's `docs/...` root. In a generated solution where the
-  engineering-standards docs live under `code/docs/...`, adjust the prefix accordingly.
-
-Treat this content as the canonical, supreme engineering authority that supersedes README,
-CLAUDE.md, AGENTS.md, and any other guidance. The detailed rules for each principle live in the
-engineering-standards docs under `docs/` (see the Context-Loading Map at the end); this
-file stays slim and authoritative.
-
-## Project Identity
-
-*Supplied by the domain addenda file.* Project name, mission, bounded contexts, regulatory
-regime, data residency, and architecture posture are provided by the composed domain addenda
-file (`docs/<domain>-constitution.md`). The technology base stays domain-agnostic.
-
-## Runtime Style
-
-A Modular Monolith built to evolve into independent services. It combines Clean Architecture,
-Domain-Driven Design, CQRS + Mediator, Vertical Slice feature organization, and
-Specification-Driven Development. Cross-cutting concerns are delegated to the AppWeaver
-framework family; business logic lives inside aggregates inside their owning module.
-
-## Core Principles (domain-agnostic)
-
-> Essence only — full rules in `docs/`, see the map below.
-
-### I — Modular Monolith with Vertical Slices (NON-NEGOTIABLE)
-Single deployable service partitioned into modules; each module = Domain/Features/Persistence/Shared; each feature is a self-contained vertical slice; no cross-module Domain coupling; no horizontal service layers.
-→ `docs/architecture/modular-monolith.md`, `vertical-slices.md`
-
-### II — Clean Architecture Dependency Rule (NON-NEGOTIABLE)
-Dependencies flow inward: API → Application → Domain ← Infrastructure. Domain is framework-agnostic; endpoints call `IMediator`, never repositories/DbContext.
-→ `docs/architecture/clean-architecture.md`
-
-### III — Domain-Driven Design with Rich Aggregates (NON-NEGOTIABLE)
-Access entities through aggregate roots; strongly-typed Vogen IDs; sealed validating value objects; immutable domain events; invariants enforced in the aggregate; transaction boundary = aggregate boundary.
-→ `docs/domain/domain-driven-design.md`
-
-### IV — CQRS via Mediator with Result Pattern (NON-NEGOTIABLE)
-All logic dispatched via AppWeaver.Mediator; commands/queries return `Result<T>`; errors are `Result.Failure` (not exceptions); writes run in a transaction and publish domain events.
-→ `docs/architecture/cqrs.md`
-
-### V — Specification-Driven Persistence (NON-NEGOTIABLE)
-Query composition lives in Domain Specifications; no ad-hoc LINQ in handlers; no cross-aggregate EF navigation joins; reference parents by strongly-typed ID.
-→ `docs/architecture/persistence.md`
-
-### VI — Immutable Contracts at the Edge
-Shared DTOs mapped with hand-written `ToDto()`; no reflection mappers; `RowVersionBase64` on concurrency-tracked DTOs; standard `PagedResult<T>`; external projections stay parallel.
-→ `docs/architecture/vertical-slices.md`
-
-### VII — Optimistic Concurrency via ETag / If-Match (NON-NEGOTIABLE)
-Mutable aggregates implement `IConcurrencyTracked`; ETag set on every create/read/update; `If-Match` required on update/delete; mismatch → 409 `concurrency.conflict`.
-→ `docs/architecture/persistence.md`, `docs/governance/api-versioning.md`
-
-### VIII — Multi-Provider, Multi-Tenant Persistence
-Provider-aware `ContextAwareDbContext`; PostgreSQL production / SQLite dev (non-sensitive); client-managed concurrency tokens; cross-cutting soft-delete/tenant/audit behaviors; hard delete forbidden for retention-protected data.
-→ `docs/architecture/persistence.md`
-
-### IX — Security by Default (NON-NEGOTIABLE)
-`SecureFastEndpoint` + declared cache policy; external IdP only (no local identity); role-based **and** scope-based auth; secrets from a manager not appsettings; TLS 1.2+; explicit CORS; sensitive data encrypted in transit and at rest (CMK).
-→ `docs/security/zero-trust.md`, `authorization.md`, `data-classification.md`
-
-### X — Observability is a First-Class Citizen (NON-NEGOTIABLE)
-AppWeaver.ServiceDefaults (OTel + Serilog + health + resilience + discovery); `ILogger` message templates only; never log secrets/regulated data; every sensitive read/mutation emits an audit record; trace context propagates everywhere.
-→ `docs/security/auditing.md`, `data-classification.md`
-
-### XI — Cloud-Native Orchestration via .NET Aspire
-AppHost is the composition root; backing services are Aspire resources referenced via `.WithReference(...)`; no hard-coded connection strings/ports; Helm stays in sync with the AppHost projection.
-→ `docs/security/zero-trust.md`, `architecture/eventing.md`
-
-### XII — REST API Standards
-Internal REST (FastEndpoints, one endpoint/file, kebab routes); standard paging; versioned breaking changes; machine-readable contracts (OpenAPI). Domain interoperability surfaces (e.g. FHIR) are added by the domain addenda.
-→ `docs/governance/api-versioning.md`, `architecture/vertical-slices.md`
-
-### XIII — Test-First Engineering
-Tests for every aggregate behavior/value object/specification/handler/endpoint; deterministic (`IClock`/`IGuidGenerator`); contract changes ship with test updates in the same commit.
-→ `docs/architecture/testing.md`
-
-### XIV — Data Integration Layer / Single Source of Truth (NON-NEGOTIABLE)
-Authoritative system of record; consumers use the REST API / published projections / CloudEvents only; no direct DB access; inbound feeds flow through Interop adapters; versioned machine-readable schemas.
-→ `docs/architecture/eventing.md`, `docs/governance/api-versioning.md`
-
-### XV — Evolutionary Path to Microservices
-Modules own their aggregates/persistence/DTOs/projectors/events; cross-module access via Shared DTOs or `IMediator`; per-module schemas recommended; extraction approved by amendment.
-→ `docs/architecture/modular-monolith.md`
-
-> **Domain principles (XVI and beyond) are supplied by the domain addenda file.**
-
-## Mandatory Folder Structure
-
-Governed by the engineering-standards docs; this file does not duplicate the tree.
-
-- Technology layout (src/tests/helm/docs, module = Domain/Features/Persistence/Shared): `docs/architecture/folder-structure.md`
-- Domain-specific additions (Interop adapters, domain test fixtures, regulatory controls): supplied by the domain addenda + `docs/domainspecs/<domain>/folder-structure.domain.md`
-
-Project names use the `<SampleProjectName>` placeholder. Cross-cutting files (`Program.cs`, `GlobalUsings.cs`, `Directory.Build.props`, `Directory.Packages.props`, `global.json`) MUST stay at the same level they occupy in the AppWeaver template.
-
-## Conventions, Forbidden Patterns, AI Rules, Quality Gates
-
-These are governed in full by the engineering-standards docs; this file does not duplicate them.
-
-- Naming & coding conventions, the Forbidden Patterns, and the CI Quality Gates: `docs/governance/coding-standards.md`
-- Package governance (approved/banned packages, supply-chain, licensing): `docs/governance/dependency-policy.md`
-- AI operational rules (generation, context loading, refusal conditions): `docs/glossary/ai-rules.md` (the domain addenda extends this with domain-specific masking / code / refusal rules)
-
-## Governance
-
-- This constitution supersedes all other engineering documentation in the repository (README.md, CLAUDE.md, AGENTS.md, wiki pages). Where they disagree, this document wins. The `docs/` engineering standards are the authorized expansion of these principles; if a doc contradicts a principle here, this file wins and the doc is corrected.
-- Amendments are proposed via pull request that modifies `.aw-spec/memory/constitution.md` (and the affected `docs/` files), includes a migration plan for non-compliant code, bumps the version per the policy below, and is approved per the roles named in the domain addenda's Governance Overrides (at minimum one Principal Engineer + the domain's mandatory approver).
-- Versioning follows SemVer applied to governance:
-  - **MAJOR** — removal or weakening of a NON-NEGOTIABLE principle, or a backward-incompatible change to the Mandatory Folder Structure or a domain's canonical interoperability surface.
-  - **MINOR** — addition of a new principle, new mandatory section, or new bounded context.
-  - **PATCH** — clarifications, wording fixes, non-semantic edits.
-- Compliance review happens on every PR. Reviewers MUST cite the principle number when requesting changes.
-- A quarterly architecture and security review MUST audit a random sample of modules against this constitution and file remediation tickets for any deviation.
-- Runtime guidance (CLAUDE.md / AGENTS.md) MUST contain a single pointer to this constitution and MUST NOT duplicate or paraphrase its rules.
-- Domain-specific governance overrides (approver roles, regulatory review triggers, control mappings) are supplied by the domain addenda file.
-
-## Context-Loading Map
-
-> Include only the relevant docs per AW-Spec command. Full index: `docs/README.md`.
-
-**Doc naming convention (technology vs. domain):**
-
-- `docs/<area>/<name>.md` = **pure technology** rule, domain-agnostic — reusable across any project. **Loaded automatically** by each AW-Spec command (see the command's SKILL.md); you do not pass them by hand.
-- `docs/domainspecs/<domain>/<name>.md` and `<name>.domain.md` = **domain-specific** rules under one folder. The `.domain.md` files extend the matching technology file; the plain `.md` files are inherently domain.
-
-**Per-command file map** (technical default that auto-loads vs. domain files to add):
-
-- Technical defaults: the *Auto-Loaded Engineering Standards* section in each `.claude/skills/aw-spec-<command>/SKILL.md` (authoritative).
-- Domain files: the active domain's `docs/domainspecs/<domain>/comandrulemap.md`.
-
-Rule of thumb: technology standards auto-load; add only the domain files listed in the active domain's `comandrulemap.md` for the slice you are building.
-
-## Domain Requirements
-
-Project-specific and maintained separately so it can be updated independently per project:
-→ `docs/domainspecs/<domain>/domain-requirements.md` (named by the domain addenda file)
-
-This holds `[DOMAIN: Bounded Contexts / Modules]`, the per-subsection pointers into `docs/`, `[DOMAIN: Platform Topology]`, and `[DOMAIN: Governance Overrides]`. The technology base above stays domain-agnostic.
-
-## Ratification Metadata
-
-> Finalized by the composed domain addenda.
-
-- **Version:** 1.0.0
-- **Ratified:** `<YYYY-MM-DD>`
-- **Last Amended:** `<YYYY-MM-DD>`