aw-spec-cli 0.1.8 → 0.1.9

package/assets/guardrails/projects/dotnet-default-project/tech-rule-bindings.md

@@ -0,0 +1,263 @@
+# dotnet-default-project — Command → Technical-Rule-File Map
+
+Per-command list of the **technical** rule files this project loads (via `resolve-tech` +
+the `tech-select` module, into the sticky standards set) for the spec-anchored
+orchestrator pipeline. This is the technical counterpart of `domain-rule-bindings.md`
+(which maps the DOMAIN rule files).
+
+**The model:** the technical rule files are CONFIGURATION — tune this map, not the
+workflows. They live in the **shared technology corpora**, one folder per stack, and this
+map is what binds a project to them. The ratified output (`constitution.technical.md`) is
+NOT listed here — every consumer refers to it directly, as-is.
+
+- All paths are workspace-relative. This project maps two stacks:
+  `guardrails/technology/dotnet-webapi/` (the service) and
+  `guardrails/technology/nextjs/` (the frontend lane). Both are **standard rules shared by
+  every project that maps them**, and neither is domain-specific. The frontend corpus is
+  read by three headings — `## /aw-spec-ui-constitution` ratifies the lane's base, and
+  `## /aw-spec-design-ui` / `## /aw-spec-implement-ui` carry the detail rules under it.
+- The two files this project authors — `service/technical-requirements.md` and
+  `frontend/ui-requirements.md` — live beside this map. They are the only mapped technical
+  files expected to differ between two projects on the same stacks.
+- `technology/dotnet-webapi/examples/` holds the worked `<SampleProjectName>` sample for the
+  rule file beside it, split out so a phase can load the rules without the sample code. The
+  code-generating phases map both; `## /aw-spec-constitution` maps the rules alone, because a
+  thin authority document has no use for sample code.
+- `resolve-tech --command <name>` collects the `- ` bullets under `## /<name>`.
+- Adding a stack is adding a corpus and mapping it — `guardrails/technology/java-spring/`
+  ships unmapped for exactly that. No workflow, script or engine change is involved.
+- **This map is pinned to .NET on purpose** — it is the *default .NET project*, and the stack
+  directories below are spelled out. Read from a repo whose lanes declare another stack,
+  `resolve-tech` returns `stack_mismatch` and `tech-select` asks before loading, because these
+  files become sticky standards the code generator follows. A project on another stack should
+  copy this folder and repoint the bullets, not adopt it as-is.
+- A bullet may name its stack with a **placeholder** instead — `{{stack}}`,
+  `{{backend_stack}}`, `{{frontend_stack}}`, `{{backend_ecosystem}}`, `{{frontend_ecosystem}}`
+  — resolved from `.appweaver/stacks.json`. `guardrails/technology/{{stack}}/persistence.md`
+  reads as `java-spring/` in a Spring repo and `dotnet-webapi/` here, so ONE map serves every
+  stack a project declares. A placeholder for an undeclared lane skips that bullet; a resolved
+  path with no file on disk is reported, not silently dropped. See STACK-PROFILES.md §7a.
+- This file is the **canonical technical mapping** for this project; it is selected whenever
+  `dotnet-default-project` is the active project (`.appweaver/domain.json`).
+- A command with no heading here loads no mapped technical file (only the workflow's
+  universal `ai-rules.md` seed + `constitution.technical.md`, referred to directly).
+- `## /aw-spec-specify` is the one **modelling-methodology** slot (see the rule partition):
+  a domain-agnostic way of *modelling*, never a technology choice. Everything below it is a
+  HOW-phase technical set.
+
+---
+
+## /aw-spec-specify
+<!-- MODELLING METHODOLOGY ONLY, in two halves. Specify is the domain phase: the single kind
+     of technical input it may take is a domain-agnostic way of MODELLING, never a technology
+     choice. Do NOT add an architecture / persistence / codegen file here — that would break
+     specify's domain purity (design/implement own those). The domain's own DDD overlay
+     (domain-driven-design.domain.md) arrives separately via domain-rule-bindings.
+
+     1. THE DOMAIN MODEL — DDD tactical patterns, plus the same methodology worked through
+        in code as the example beside it.
+     2. THE EXPERIENCE MODEL — the ux/ rules that govern how specify states the experience:
+        Experience Scope, and the project-wide Experience Standards it lifts as UX- ids for
+        prototype / design-ui / implement-ui to author and verify against. These are
+        methodology, not visual design; each file's own "What must NOT appear" section is
+        what keeps screens out of the spec.
+
+     ⚠ The ux/ files sit in a DOMAIN corpus folder but are TECHNICAL-tier inputs: a file's
+     tier is the map that lists it, not the folder it lives in. guardrails/domain/healthcare/
+     ihe-conformance.md under ## /aw-spec-design is the same pattern. Unmapping them does not
+     make the spec's Experience Standards section disappear — the section is unconditional and
+     resolves to "None" — it removes the methodology specify fills it from. -->
+- guardrails/technology/dotnet-webapi/domain-driven-design.md
+- guardrails/technology/dotnet-webapi/examples/domain-driven-design.md
+- guardrails/domain/healthcare/ux/journey-mapping.md
+- guardrails/domain/healthcare/ux/interaction-states.md
+- guardrails/domain/healthcare/ux/accessibility-standards.md
+- guardrails/domain/healthcare/ux/content-design.md
+
+## /aw-spec-design
+<!-- The technical/architecture rule files the design author works from (alongside the
+     spec and constitution.technical.md), each followed by its worked example. NO domain file
+     here — domain reaches design only as spec ids (BR-/CN-/DC-/IC-). -->
+- guardrails/technology/dotnet-webapi/clean-architecture.md
+- guardrails/technology/dotnet-webapi/cqrs.md
+- guardrails/technology/dotnet-webapi/eventing.md
+- guardrails/technology/dotnet-webapi/modular-monolith.md
+- guardrails/technology/dotnet-webapi/vertical-slices.md
+- guardrails/technology/dotnet-webapi/persistence.md
+- guardrails/technology/dotnet-webapi/folder-structure.md
+- guardrails/technology/dotnet-webapi/testing.md
+- guardrails/technology/dotnet-webapi/api-versioning.md
+- guardrails/technology/dotnet-webapi/zero-trust.md
+- guardrails/technology/dotnet-webapi/authorization.md
+- guardrails/technology/dotnet-webapi/authorization-matrix.md
+- guardrails/technology/dotnet-webapi/auditing.md
+- guardrails/technology/dotnet-webapi/data-classification.md
+- guardrails/domain/healthcare/ihe-conformance.md
+- guardrails/technology/dotnet-webapi/examples/clean-architecture.md
+- guardrails/technology/dotnet-webapi/examples/cqrs.md
+- guardrails/technology/dotnet-webapi/examples/eventing.md
+- guardrails/technology/dotnet-webapi/examples/vertical-slices.md
+- guardrails/technology/dotnet-webapi/examples/persistence.md
+- guardrails/technology/dotnet-webapi/examples/api-versioning.md
+- guardrails/technology/dotnet-webapi/examples/zero-trust.md
+- guardrails/technology/dotnet-webapi/examples/authorization.md
+- guardrails/technology/dotnet-webapi/examples/auditing.md
+
+## /aw-spec-design-ui
+<!-- The FRONTEND LANE's design phase. Its own heading, not a branch of ## /aw-spec-design:
+     the two lanes are governed by different constitution halves and own disjoint source
+     paths, so keying the map on this command name gives the lane its own rule set for zero
+     mechanism change. NO domain file here — the domain reaches design.ui.md as spec ids,
+     exactly as it reaches design.md. The lane's ratified base (constitution.ui.md) is
+     referred to directly and is NOT mapped.
+
+     THE SERVICE LANE ENTERS THROUGH ONE FILE. api-integration.{{backend_stack}}.md is the
+     CROSS-LANE pairing rule set — what the service guarantees (paging shape, concurrency
+     token, error codes, redaction, caching, CORS) and what the client therefore must do.
+     It is named for the service stack and mapped through the placeholder, so ONE bullet
+     serves every backend: it resolves to api-integration.dotnet-webapi.md here and to
+     api-integration.java-spring.md in a Spring repo — both authored — and to a REPORTED
+     missing file for a backend whose pairing nobody has written yet, rather than silently
+     loading one stack's assumptions into another. A repo with no backend lane skips the
+     bullet entirely. No other service-lane file is mapped here: design.ui.md consumes the
+     published surface, never the service's internals. -->
+- guardrails/technology/nextjs/component-architecture.md
+- guardrails/technology/nextjs/routing-navigation.md
+- guardrails/technology/nextjs/state-management.md
+- guardrails/technology/nextjs/error-handling.md
+- guardrails/technology/nextjs/forms-and-validation.md
+- guardrails/technology/nextjs/auth-session.md
+- guardrails/technology/nextjs/design-system.md
+- guardrails/technology/nextjs/accessibility-implementation.md
+- guardrails/technology/nextjs/i18n.md
+- guardrails/technology/nextjs/performance-budgets.md
+- guardrails/technology/nextjs/api-integration.{{backend_stack}}.md
+
+## /aw-spec-implement
+<!-- The FRAMEWORK / code-generation rule files the code generator builds against
+     (alongside design.md and constitution.technical.md). NO domain file — domain
+     reaches implement only through design.md. clean-architecture/cqrs are design
+     concerns; component wiring is a separate /appweaver add-component step. -->
+- guardrails/technology/dotnet-webapi/coding-standards.md
+- guardrails/technology/dotnet-webapi/dependency-policy.md
+- guardrails/technology/dotnet-webapi/folder-structure.md
+- guardrails/technology/dotnet-webapi/testing.md
+- guardrails/technology/dotnet-webapi/PACKAGING.md
+
+## /aw-spec-implement-ui
+<!-- The FRONTEND LANE's code-generation set — the HOW the UI generator builds against,
+     alongside design.ui.md and constitution.ui.md. NO domain file: domain reached the lane
+     through spec -> design.ui.md. NO service-lane file beyond the pairing rules below —
+     this phase never writes outside the lane's declared source path.
+
+     EIGHT FILES ARE MAPPED FOR BOTH LANE PHASES on purpose. error-handling,
+     forms-and-validation, auth-session, design-system, accessibility-implementation, i18n,
+     performance-budgets and the api-integration pairing each carry a DESIGN half and an
+     IMPLEMENT half of one rule: the design decides the states, the affordances and the
+     targets; this phase realises them. A rule read by only one of the two loses the
+     pairing, and the half that goes unread is always the one that then goes unbuilt. -->
+- guardrails/technology/nextjs/component-conventions.md
+- guardrails/technology/nextjs/api-client.md
+- guardrails/technology/nextjs/api-integration.{{backend_stack}}.md
+- guardrails/technology/nextjs/auth-session.md
+- guardrails/technology/nextjs/client-security.md
+- guardrails/technology/nextjs/error-handling.md
+- guardrails/technology/nextjs/forms-and-validation.md
+- guardrails/technology/nextjs/design-system.md
+- guardrails/technology/nextjs/accessibility-implementation.md
+- guardrails/technology/nextjs/i18n.md
+- guardrails/technology/nextjs/performance-budgets.md
+- guardrails/technology/nextjs/observability.md
+- guardrails/technology/nextjs/frontend-testing.md
+
+## /aw-spec-implement-delta
+<!-- The CR analog of implement — same FRAMEWORK / code-generation set (HOW to build).
+     The delta's code is generated against the master design.md + delta-design.md; no
+     domain file (domain reached the delta via delta-spec → delta-design). -->
+- guardrails/technology/dotnet-webapi/coding-standards.md
+- guardrails/technology/dotnet-webapi/dependency-policy.md
+- guardrails/technology/dotnet-webapi/folder-structure.md
+- guardrails/technology/dotnet-webapi/testing.md
+- guardrails/technology/dotnet-webapi/PACKAGING.md
+
+## /aw-spec-build
+<!-- The compile/fix reference set: the layering + coding rules the fixer respects when
+     repairing compile errors against the design intent, plus the layering example it repairs
+     towards. NO domain file (build loads domain rules separately via domain-select) and no
+     constitution.technical here. -->
+- guardrails/technology/dotnet-webapi/clean-architecture.md
+- guardrails/technology/dotnet-webapi/coding-standards.md
+- guardrails/technology/dotnet-webapi/examples/clean-architecture.md
+
+## /aw-spec-analyze-slice
+<!-- The design↔code conformance gate's TECHNICAL checklist: the code + tests are
+     validated against these (alongside the DOMAIN gate overlays, loaded separately via
+     resolve-domain `## /aw-spec-gate`). Validation input only — never authoring. -->
+- guardrails/technology/dotnet-webapi/testing.md
+- guardrails/technology/dotnet-webapi/coding-standards.md
+
+## /aw-spec-constitution
+<!-- What the TECHNICAL half of the split constitution ratifies into
+     constitution.technical.md: the technology base, then the STANDARD technical rules for
+     this industry — the same corpus design and implement build against, so a ratified
+     principle can cite the rule it governs — and last the PROJECT-SUPPLIED file the project
+     team authors. Loaded BEFORE the technical half and before domain-select, so the
+     technical author stays domain-free (the seam). NO domain file here: the domain half's
+     sources are the domain map's ## /aw-spec-constitution. NO examples/ file either — the
+     ratified half is one declarative line and a `→` pointer per principle, so sample code is
+     weight without a reader. -->
+- guardrails/technology/dotnet-webapi/technology-constitution.md
+- guardrails/technology/dotnet-webapi/clean-architecture.md
+- guardrails/technology/dotnet-webapi/modular-monolith.md
+- guardrails/technology/dotnet-webapi/vertical-slices.md
+- guardrails/technology/dotnet-webapi/cqrs.md
+- guardrails/technology/dotnet-webapi/persistence.md
+- guardrails/technology/dotnet-webapi/eventing.md
+- guardrails/technology/dotnet-webapi/folder-structure.md
+- guardrails/technology/dotnet-webapi/testing.md
+- guardrails/technology/dotnet-webapi/zero-trust.md
+- guardrails/technology/dotnet-webapi/authorization.md
+- guardrails/technology/dotnet-webapi/auditing.md
+- guardrails/technology/dotnet-webapi/data-classification.md
+- guardrails/technology/dotnet-webapi/api-versioning.md
+- guardrails/technology/dotnet-webapi/coding-standards.md
+- guardrails/technology/dotnet-webapi/dependency-policy.md
+- guardrails/projects/dotnet-default-project/service/technical-requirements.md
+
+## /aw-spec-ui-constitution
+<!-- What the UI half ratifies into constitution.ui.md as a UX-* principle series: the
+     standard frontend rules for this industry, then the PROJECT-SUPPLIED file. This heading
+     is also the AUTHORITATIVE signal that the project HAS a frontend lane — with no heading
+     here the constitution command skips the UI half and creates no file at all. Domain-free,
+     and loaded before domain-select for the same reason as the set above. -->
+- guardrails/technology/nextjs/ui-constitution.md
+- guardrails/projects/dotnet-default-project/frontend/ui-requirements.md
+
+## /aw-spec-run
+<!-- Execution / data migration: the persistence rules the migration step generates against,
+     plus their worked example. NO domain file; run does not reference constitution.technical.md. -->
+- guardrails/technology/dotnet-webapi/persistence.md
+- guardrails/technology/dotnet-webapi/examples/persistence.md
+
+---
+
+## Quick reference (command → technical file count)
+
+| Command | Technical rule files | Role |
+|---|---|---|
+| /aw-spec-specify | 6 | the modelling methodology the spec is expressed in: DDD for the domain model (+ its example), and the four ux/ rules for the experience model it lifts as UX- ids — no technology |
+| /aw-spec-design | 24 | architecture/security/interop the design author mediates the spec against, each with its example |
+| /aw-spec-design-ui | 11 | the frontend lane's design set — composition, routing, client state, interaction states, forms, auth surface, design system, accessibility, i18n, performance, and the cross-lane API pairing the UI design author works from (from spec.md) |
+| /aw-spec-implement | 5 | governance/architecture the code generator builds against (from design.md) |
+| /aw-spec-implement-ui | 13 | the frontend lane's code-generation set the UI generator builds against (from design.ui.md) — conventions, the generated client + its service pairing, auth, client security, states, forms, design system, accessibility, i18n, performance, observability and testing |
+| /aw-spec-implement-delta | 5 | same code-generation set, scoped to the open change's delta-design |
+| /aw-spec-build | 3 | layering + coding rules the compile-fixer respects, + the layering example |
+| /aw-spec-analyze-slice | 2 | testing + coding rules the design↔code gate validates against |
+| /aw-spec-constitution | 17 | what the technical half ratifies — the technology base, the standard technical rules, and the project team's technical-requirements.md |
+| /aw-spec-ui-constitution | 2 | what the frontend lane's half ratifies — the UI base + the project team's ui-requirements.md — and the signal that the lane exists |
+| /aw-spec-run | 2 | persistence rules the execution / data-migration step generates against, + its example |
+
+> All migrated workflows are on this map. The conformance-gate workflows **analyze-design**
+> and **analyze-delta-design** are intentionally NOT here — they validate design/delta
+> against the spec + DOMAIN gate overlays only (domain-rule-bindings `## /aw-spec-gate`), with no
+> technical gate checklist.

package/assets/guardrails/requirement-spec.txt

@@ -0,0 +1,27 @@
+MedicinalProduct/
+
+/appweaver constitution
+
+/appweaver specify RegisterMedicinalProduct
+
+Allow an authorized user to register a new medicinal product in the registry.
+
+On registration the user provides: product name, generic name, NDC, dosage form, strength, route of administration, manufacturer, one or more active ingredients with details, one or more packaging configurations and one or more ATC classification codes.
+
+The system validates the submission (required attributes, duplicate NDC, valid dosage form and route of administration) and creates the product in the Draft state. A successful registration is auditable and emits a registration event.
+
+Acceptance:
+- A valid submission creates a Draft MedicinalProduct and returns its identifier.
+- A malformed or duplicate NDC is rejected with a clear validation error.
+- A product missing a required attribute, an active ingredient, or a packaging configuration is rejected.
+- The creation is recorded in the audit trail.
+
+/appweaver design 
+
+/appweaver analyze-design
+
+/appweaver implement
+
+
+
+==============================================================================================

package/assets/guardrails/technology/dotnet-webapi/PACKAGING.md

@@ -0,0 +1,184 @@
+# VerticalSlice — Foundation Packaging Rules
+
+> **Why this exists.** The old `/aw-spec-foundation` skill *reconstructed* every project
+> file from prose rule docs. Any omission or namespace drift produced a broken,
+> non-compiling skeleton. This packaging model replaces reconstruction with a
+> **byte-for-byte bundle of a real, verified solution**.
+>
+> You build the foundation **once** (a solution that actually compiles and runs),
+> pack it into a single text file, and the scaffolder just **unpacks + renames** it.
+> No regeneration, no drift.
+
+---
+
+## The single artifact
+
+```
+foundations/dotnet/VerticalSlice/
+├── VerticalSlice.pack.txt      ← THE BUNDLE: every source file, in one text file
+├── pack-foundation.ps1         ← produces VerticalSlice.pack.txt from a solution
+└── unpack-foundation.ps1       ← extracts + renames into a target app (used by the skill)
+```
+
+The bundle is the single source of truth for scaffolding. The engineering standards
+the foundation solution must satisfy (vertical slices, DDD, CQRS, persistence, etc.)
+live in the project constitution and the domain-specs rule files, not in this folder.
+
+---
+
+## The sentinel convention
+
+You author the foundation solution under one fixed **sentinel app name**:
+
+```
+AppWeaver.Foundation
+```
+
+This is the placeholder that the scaffolder rewrites into the caller's app name.
+It must be a **distinctive two-segment token** that is **not a prefix of any
+`AppWeaver.*` NuGet package** (it isn't — there is no `AppWeaver.Foundation` package),
+so a full-token replacement can never clobber a framework reference.
+
+The scaffolder rewrites the sentinel in **four case forms** (ordinal, case-sensitive),
+applied to **file contents and to file/folder paths**:
+
+| Form        | Sentinel               | Example target (`AppWeaver.Health`) | Where it appears                                  |
+|-------------|------------------------|-------------------------------------|---------------------------------------------------|
+| dotted      | `AppWeaver.Foundation` | `AppWeaver.Health`                  | namespaces, `.csproj`/`.sln` names, project refs  |
+| underscored | `AppWeaver_Foundation` | `AppWeaver_Health`                  | Aspire project class names (`Projects.X_Service`) |
+| lower-hyphen| `appweaver-foundation` | `appweaver-health`                  | `UserSecretsId`, db/container names               |
+| lower-dot   | `appweaver.foundation` | `appweaver.health`                  | any lowercased identifiers                         |
+
+**Never** rename the bare `AppWeaver` company segment on its own — only the full
+sentinel token in the forms above. The framework packages (`AppWeaver.Mediator`,
+`AppWeaver.Repository`, …) stay exactly as written.
+
+### What does NOT get renamed
+
+- `AppWeaver.*` framework package references (`Directory.Packages.props`, every `.csproj`).
+- The sample domain folder **`Projects`** (aggregate `Project`, `CreateProject`, etc.).
+  This is intentional sample content the caller renames to their own bounded context later.
+- `<Company>` / `<Authors>` metadata in `Directory.Build.props` (display-only; edit manually if desired).
+
+---
+
+## How to author the foundation solution (do this once)
+
+1. **Pick a scratch folder** outside `foundations/`, e.g.
+   `E:\Work\Bytestrone\AppWeaver\Testing\AppWeaver.Spec\.foundation-build\`.
+2. **Create the solution under the sentinel name** `AppWeaver.Foundation`, following the
+   engineering standards in the project constitution and domain-specs rule files:
+   ```
+   AppWeaver.Foundation.sln
+   global.json
+   Directory.Build.props
+   Directory.Packages.props
+   src/
+     AppWeaver.Foundation.AppHost/
+     AppWeaver.Foundation.ServiceDefaults/
+     AppWeaver.Foundation.Service/        (includes the sample 'Projects' domain)
+     AppWeaver.Foundation.Web/
+   ```
+3. **Make it actually work.** This is the whole point — the bundle is only as good as
+   the solution you pack. Verify before packing:
+   ```powershell
+   dotnet restore .foundation-build/AppWeaver.Foundation.sln
+   dotnet build   .foundation-build/AppWeaver.Foundation.sln -c Debug
+   # optional end-to-end:
+   dotnet run --project .foundation-build/src/AppWeaver.Foundation.AppHost
+   ```
+   Fix every error and warning-as-error here, in the real project, where the compiler
+   tells you exactly what's wrong. The packed bundle inherits this correctness.
+4. **Use the sentinel everywhere** the app name belongs: namespaces, project/folder
+   names, `UserSecretsId`, the Aspire db resource name, container names. Use the correct
+   case form for each (see table above).
+
+---
+
+## How to build the bundle
+
+From `foundations/dotnet/VerticalSlice/`:
+
+```powershell
+# This foundation intentionally ships the org-internal Azure Artifacts PAT in NuGet.config,
+# so the secret guard must be overridden with -AllowSecrets (org-internal use only — rotate periodically).
+./pack-foundation.ps1 -SourceDir ../../../.foundation-build -OutFile ./VerticalSlice.pack.txt -AllowSecrets
+```
+
+The packer:
+
+- walks the solution, **excluding** build/IDE artifacts and secret-bearing files:
+  - dirs: `bin obj .vs .git .idea .vscode TestResults node_modules packages App_Data artifacts .next logs`
+  - files: `*.user *.suo *.DotSettings.user *.db *.db-shm *.db-wal *.sqlite *.log`
+    and **secrets**: `.env.* *.pfx *.pem *.key *.snk id_rsa id_rsa.pub secrets.json`;
+    > The root **`.env` is bundled on purpose** (required sample config); only per-environment
+    > overrides (`.env.local`, `.env.production`, …) are excluded. Keep the bundle org-internal
+    > and rotate any real values — the content scan still blocks PATs/keys regardless of filename.
+- **fails closed on detected secrets** — it scans file *contents* for credential markers
+  (`ClearTextPassword`, private-key blocks, AWS keys, Azure DevOps PAT patterns) and
+  **refuses to pack** if any are found, unless you pass `-AllowSecrets`. This is what stops
+  a `NuGet.config` PAT from being baked into the committed bundle. **Fix the source** (rotate
+  the secret, switch the feed to env/CLI auth) rather than overriding the guard;
+- stores text files **verbatim** and binary files (e.g. a `.png`) **base64-encoded**;
+- writes a header (foundation, sentinel, file count, format version, replacement contract);
+- **warns** if the sentinel token appears in zero files (a sign you used the wrong name).
+
+> **Credentials in a scaffold.** The bundled `NuGet.config` should contain only feed
+> *definitions* and `packageSourceMapping` — never `<packageSourceCredentials>`. Developers
+> authenticate to private feeds with `dotnet nuget` / the Azure Artifacts credential provider
+> / environment variables, not a checked-in PAT.
+
+Re-run it whenever the foundation changes; commit the regenerated `VerticalSlice.pack.txt`.
+
+---
+
+## Pack file format (`aw-spec-pack/v1`)
+
+```
+# AW-SPEC FOUNDATION PACK
+# foundation: VerticalSlice
+# sentinel: AppWeaver.Foundation
+# generated: 2026-06-14T10:00:00.0000000Z
+# files: 47
+# format: aw-spec-pack/v1
+# --- replacement contract ... ---
+# ============================================================
+
+<<<FILE path="Directory.Build.props">>>
+...verbatim file content...
+<<<ENDFILE>>>
+<<<FILE path="src/AppWeaver.Foundation.AppHost/Program.cs">>>
+...verbatim file content...
+<<<ENDFILE>>>
+<<<FILE path="src/AppWeaver.Foundation.Web/wwwroot/favicon.ico" encoding="base64">>>
+AAABAAE...
+<<<ENDFILE>>>
+```
+
+- Paths are repo-root-relative with `/` separators.
+- The marker lines `<<<FILE …>>>` and `<<<ENDFILE>>>` are **reserved** — they must never
+  occur as a literal line inside a source file (they can't in C#/XML/JSON/Razor).
+- `encoding="base64"` marks a binary file; everything else is UTF-8 text.
+
+---
+
+## How scaffolding consumes the bundle
+
+`/appweaver foundation VerticalSlice <AppName> [OutputDir]` runs `unpack-foundation.ps1`,
+which reads the sentinel from the pack header, derives the four target case forms, and
+writes the renamed files to the output directory (**repo root by default**). The phase is
+defined in `.appweaver/orchestrator/workflows/aw-spec-foundation.orch.yaml`.
+
+```powershell
+./unpack-foundation.ps1 -PackFile ./VerticalSlice.pack.txt -TargetAppName AppWeaver.Health -OutDir ../../../ 
+```
+
+---
+
+## Maintenance checklist
+
+- [ ] Foundation solution builds clean (`dotnet build`, warnings-as-errors satisfied).
+- [ ] Sentinel `AppWeaver.Foundation` used consistently in all four case forms.
+- [ ] No `bin/obj/.vs` or local `.db` files committed into the pack.
+- [ ] `pack-foundation.ps1` reported a non-zero sentinel hit count.
+- [ ] `VerticalSlice.pack.txt` regenerated and committed after any change.

package/assets/guardrails/technology/dotnet-webapi/api-versioning.md

@@ -0,0 +1,44 @@
+# API Versioning Policy
+
+> Pure technology (domain-agnostic) — domain (e.g. FHIR) versioning in [[api-versioning.domain]]. Commands: `/aw-spec-design`.
+
+## REST versioning
+
+- Internal REST (FastEndpoints) serves first-party apps and operational tooling.
+- List endpoints accept `pageNumber` (1-based) + `pageSize` and return `PagedResult<TDto>`
+  (see [[vertical-slices]]).
+- Breaking changes to internal REST require a **versioned route prefix** (`v2/...`).
+- Endpoints MUST NOT swallow exceptions; the central exception handler owns the contract.
+
+## ETag / concurrency at the edge
+
+- The server sets the ETag header on every create/read/update via `SetETagFromBase64(...)`.
+- Update/Delete extract `If-Match` via `GetIfMatchBase64Token()`; mismatch -> `409
+  concurrency.conflict`. ETag tokens are strong; `W/` weak prefixes stripped on read.
+  See [[persistence]].
+
+## Machine-readable schemas
+
+- The service publishes versioned, machine-readable schemas:
+  - **OpenAPI** for REST,
+  - **AsyncAPI** for events (see [[eventing]]).
+- All schemas regenerate cleanly in CI; diffs are reviewed for breaking changes
+  (see [[coding-standards]]).
+- (FHIR CapabilityStatement — see [[api-versioning.domain]].)
+
+## Deprecation lifecycle & sunset policy
+
+- **Breaking changes are MAJOR version bumps** (per the constitution's governance SemVer).
+- A superseded REST version remains available through a documented deprecation window before
+  sunset; the deprecation and sunset are announced via the published schema diffs and the
+  governance amendment process.
+
+## Canonical example
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/api-versioning.md`, mapped for `design`. The
+constitution set maps the rules without it.
+
+## Related
+
+- [[vertical-slices]] · [[persistence]] · [[eventing]] · [[coding-standards]] · [[api-versioning.domain]]

package/assets/guardrails/technology/dotnet-webapi/auditing.md

@@ -0,0 +1,96 @@
+# Auditing & Observability Standards
+
+> Pure technology (domain-agnostic) — domain audit additions in [[auditing.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-design`.
+
+## Observability baseline
+
+- All services consume `AppWeaver.ServiceDefaults` (`builder.AddServiceDefaults()`):
+  OpenTelemetry (ASP.NET Core, HttpClient, EF Core, runtime), Serilog structured logging with
+  enrichment (environment/machine/thread/correlation IDs), health checks at `/health` and
+  `/alive`, standard HTTP resilience handlers, and Aspire service discovery.
+
+## Structured logging
+
+- All logging goes through `ILogger<T>` with **message templates** (no string interpolation in
+  log calls).
+- `Console.WriteLine`, `Debug.WriteLine`, and `System.Diagnostics.Trace` are **forbidden** in
+  production code.
+- Log levels: Information (state transitions), Warning (recoverable anomalies), Error
+  (handled failures), Critical (invariant breaches). Debug/Trace MUST be safe to enable in
+  production.
+
+## Metrics & tracing
+
+- Custom metrics follow OTel semantic conventions, registered via a single `Meter` per module.
+- Trace context MUST propagate across `IMediator.Send`, `HttpClient`, and EF Core; bypassing
+  the framework's `HttpClientFactory` is forbidden.
+
+## Secrets never in telemetry
+
+- Authentication tokens, password material, private keys, and full payment-card numbers MUST
+  NEVER appear in logs, metrics labels, exception messages, or trace attributes.
+  (Domain-sensitive data — PHI, SSN, government IDs — see [[data-classification.domain]] and
+  [[auditing.domain]].)
+
+## Immutable audit strategy (generic)
+
+- Audit records are **append-only**: no update, no delete (no hard-delete path).
+- An audit-access pipeline behavior runs on every mediator request (see [[cqrs]]).
+- Audit records are retained per the applicable retention policy (see [[persistence]];
+  regulatory retention in [[auditing.domain]]).
+
+## Two auditing levels
+
+Auditing has exactly **two levels**, chosen **per aggregate** by the marker interfaces the root
+implements. The interceptor populates every audit field automatically (no manual
+`CreatedOn`/`ModifiedBy` assignment in handlers):
+
+| Level | Aggregate root implements | Captured | Depth |
+|-------|---------------------------|----------|-------|
+| **Basic** | `IAuditedObject` (creation+modification) or `IFullAuditedObject` (+soft-delete) | `CreatedBy/On`, `ModifiedBy/On`, `DeletedBy/On`; one `AuditLog` per root per SaveChanges | entity-level (Created/Updated/Deleted) — no before/after |
+| **Advanced** | Basic markers **+ `IFieldAudited`** | Basic + field-level before/after (`PropertyChange`: original → new) | entity + property-level previous/new |
+
+Field-level before/after values exist **only** at the Advanced tier. Children marked
+`IAggregateChild` fold into the root's `AuditLog`.
+
+## Canonical example
+
+The worked `<SampleProjectName>` example for these rules lives in
+`guardrails/technology/dotnet-webapi/examples/auditing.md`, mapped for `design`. The
+constitution set maps the rules without it.
+
+## Querying the audit trail (framework-provided)
+
+The audit store is queryable out of the box via `IAuditEntity` — no bespoke read model required:
+
+```csharp
+// by resource identity
+var logs = await auditEntity.GetAuditLogsAsync(typeof(Project).FullName!, projectId.ToString());
+// by user / action / time, with paging
+var page = await auditEntity.GetAuditLogsAsync(new AuditLogFilter { UserId = "u1", Action = AuditAction.Updated, Take = 10 });
+// by user / tenant
+await auditEntity.GetAuditLogsByUserAsync("u1");
+await auditEntity.GetAuditLogsByTenantAsync("tenant-alpha");
+```
+
+Each `AuditLog` carries `{ UserId, UserName, Timestamp, Action, EntityType, EntityId, Metadata
+(correlationId, …) }`; its `EntityChanges` hold entity-level `ChangeType`, and — for `IFieldAudited`
+roots — nested `PropertyChanges` with `OriginalValue → NewValue`.
+
+Observability baseline — `ServiceDefaults` (OTel + Serilog + health) wired once in `Program.cs`:
+
+```csharp
+// <SampleProjectName>.Service/Program.cs
+builder.AddServiceDefaults();                 // OTel, resilience, service discovery, health
+Log.Logger = new LoggerConfiguration()
+    .ReadFrom.Configuration(builder.Configuration)
+    .Enrich.FromLogContext()
+    .CreateLogger();
+builder.Host.UseSerilog();
+// ...
+app.MapDefaultEndpoints();                     // /health, /alive
+```
+
+## Related
+
+- [[data-classification]] · [[cqrs]] · [[persistence]] · [[auditing.domain]]

package/assets/guardrails/technology/dotnet-webapi/authorization-matrix.md

@@ -0,0 +1,14 @@
+# Authorization Matrix
+
+Per-route role + SMART-scope authorization (authorization.domain). PHI endpoints are
+`SecurityLevel.Restricted`, `CachePolicy.NoStore`, and emit ATNA audit records.
+
+| Route | Method | Roles | SMART scope | Security level | Notes |
+|---|---|---|---|---|---|
+| `/patients` | POST | `FrontDesk`, `SystemAdmin`, `ExternalSystem` | `system/Patient.write` or `user/Patient.write` | Restricted | Register patient (PHI write). 400/409/422 per spec. |
+| `/fhir/R4/Patient/{id}` | GET | `Physician`, `Nurse`, `SystemAdmin`, `ExternalSystem` | `patient/Patient.read`, `user/Patient.read`, or `patient/Patient.read.full` for un-redacted demographics | Restricted | Minimum-necessary redaction in the projection extension. |
+| `/fhir/metadata` | GET | — (anonymous) | — | Public | CapabilityStatement (infra/discovery allowlist). |
+| HL7 v2 MLLP ingress (ADT^A04) | MLLP | `ExternalSystem` (node-authenticated) | n/a | Restricted | Receipt ACK; async registration via canonical command. |
+
+> The `patient/Patient.read.full` scope gates full demographics (telecom/address/secondary identifiers);
+> without it the FHIR read returns identity essentials only.