aw-spec-cli 0.1.4 → 0.1.6

package/assets/docs/command.txt

@@ -1,295 +0,0 @@
-================================================================================
-AW-SPEC COMMAND SHEET — Feature: Patient Registration  (Patient / RegisterPatient)
-================================================================================
-Run these in order, one per turn, from /aw-spec-specify to /aw-spec-implement.
-All six numbered steps are REQUIRED for this feature — clarify and analyze are
-correctness gates, not optional extras (see their sections for why).
-
-CONVENTIONS USED BELOW
-- @paths are Claude Code file mentions; they are inlined as context. Paths are
-  relative to the workspace root (e:\Work\Company\Project), so they start with `docs/...`.
-- "MANUAL TEXT" = the plain prompt you type as part of the command.
-- The spec folder convention is specs/<Aggregate>/<Feature>; starting the feature
-  description with the token `Patient/RegisterPatient` makes /aw-spec-specify create
-  specs/Patient/RegisterPatient/ and pin it in .aw-spec/feature.json. Every later
-  command (clarify/plan/tasks/analyze/implement) auto-resolves that folder from
-  feature.json — you do NOT pass the aggregate/feature token again.
-- The constitution (.aw-spec/memory/constitution.md) AND the domain-agnostic technical
-  standards are AUTO-LOADED by each command (see each SKILL.md) — you
-  do NOT pass those with @.
-- The DOMAIN-SPECIFIC files shown per step come from the active domain's comandrulemap.md
-  (active domain = .aw-spec/domain.json, set via /aw-spec-select-domain). Each command offers
-  them in a selection box (Select all / Pick a subset / None); the @ mentions below are an
-  equivalent, OPTIONAL shortcut and are always loaded in addition to the auto-loaded set.
-
-INTEROPERABILITY SCOPE FOR THIS FEATURE
-  Patient registration is an interoperability-heavy feature. It MUST support:
-   - Inbound HL7 v2 ADT^A04 (Register a Patient) via an Interop/Hl7v2 adapter that
-     converts the message to the RegisterPatientCommand (never writes to the aggregate
-     directly), over MLLP, with ACK handling.
-   - Outbound ADT emission on PatientRegisteredEvent (egress adapter).
-   - External FHIR R4 Patient projection + PIX/PDQ identity cross-reference.
-  Therefore docs/domainspecs/healthcare/hl7.md and the eventing docs are part of the context from
-  specify through implement.
-
-SETUP (one-time per project) — set the active domain
-  /aw-spec-select-domain              (lists docs/domainspecs/ folders; writes .aw-spec/domain.json)
-  /aw-spec-select-domain healthcare   (or set it directly)
-  -> For this demo the domain is `healthcare` (already set). If the domain is unset or its
-     comandrulemap.md is missing, every command first asks "Continue without domain rules?
-     (Continue / Exit)" before running.
-
-PREREQUISITE (one-time, only if the constitution has not been ratified yet)
-  /aw-spec-constitution @docs/healthcare-constitution.md @docs/domainspecs/healthcare/domain-requirements.md
-  -> docs/technology-constitution.md auto-loads (technology base); pass only the domain addenda.
-  -> Ratifies .aw-spec/memory/constitution.md. Not part of the per-feature loop.
-
-
-================================================================================
-STEP 1 — /aw-spec-specify   (create the feature spec)
-================================================================================
-PURPOSE
-  Create specs/Patient/RegisterPatient/spec.md (WHAT/WHY, no implementation detail)
-  and pin the folder in .aw-spec/feature.json. A git feature branch is created by the
-  before_specify hook.
-
-CONTEXT FILES TO ADD
-  docs/domainspecs/healthcare/domain-requirements.md          (bounded contexts: Patient aggregates)
-  docs/domainspecs/healthcare/clinical-terms.md             (MRN, Encounter, Coverage, ...)
-  docs/domainspecs/healthcare/integration-terms.md          (FHIR, HL7, PIX/PDQ, ATNA, ADT)
-  docs/domainspecs/healthcare/domain-driven-design.domain.md  (Patient invariants)
-  docs/domainspecs/healthcare/fhir.md                          (Patient FHIR projection)
-  docs/domainspecs/healthcare/hl7.md                           (HL7 v2 ADT ingestion/egress)  <-- HL7
-  docs/domainspecs/healthcare/dicom.md                         (imaging identifiers; optional for registration)
-  docs/domainspecs/healthcare/terminology.md                   (coded fields)
-  docs/domainspecs/healthcare/hipaa.md                          (PHI / minimum-necessary)
-  docs/domainspecs/healthcare/consent.md                        (Consent at registration)
-  docs/domainspecs/healthcare/data-classification.domain.md   (PHI/PII categories)
-  docs/domainspecs/healthcare/ai-rules.domain.md              (PHI masking, no invented codes)
-
-COMMAND (copy-paste, single line)
-/aw-spec-specify Patient/RegisterPatient Register a new patient into the master patient index. Capture demographics (legal HumanName, date of birth, administrative sex, contact points, address) and assign a tenant-unique MRN. Invariants: MRN is unique per tenant; date-of-birth must not be in the future; minimum-necessary projection by role/scope. Interoperability: inbound HL7 v2 ADT^A04 (Register a Patient) messages MUST be ingested through an Interop/Hl7v2 adapter that converts to the RegisterPatientCommand (no direct aggregate writes) over MLLP with ACK handling, and an outbound ADT emitter fires on PatientRegisteredEvent; also expose an external FHIR R4 Patient projection and PIX/PDQ identity cross-reference. Surfaces: internal REST POST /patients returning the created Patient, the FHIR R4 Patient endpoint, and the HL7 v2 ADT ingress channel. Every PHI read/write must produce an ATNA audit record. Out of scope: patient merge, portal self-registration. @docs/domainspecs/healthcare/domain-requirements.md @docs/domainspecs/healthcare/clinical-terms.md @docs/domainspecs/healthcare/integration-terms.md @docs/domainspecs/healthcare/domain-driven-design.domain.md @docs/domainspecs/healthcare/fhir.md @docs/domainspecs/healthcare/hl7.md @docs/domainspecs/healthcare/dicom.md @docs/domainspecs/healthcare/terminology.md @docs/domainspecs/healthcare/hipaa.md @docs/domainspecs/healthcare/consent.md @docs/domainspecs/healthcare/data-classification.domain.md @docs/domainspecs/healthcare/ai-rules.domain.md
-
-MANUAL TEXT (the prompt portion, for reference)
-  Patient/RegisterPatient Register a new patient into the master patient index. Capture
-  demographics (legal HumanName, date of birth, administrative sex, contact points,
-  address) and assign a tenant-unique MRN. Optionally link an insurance Coverage and
-  capture initial patient Consent. Invariants: MRN is unique per tenant; date-of-birth
-  must not be in the future; minimum-necessary projection by role/scope.
-  Interoperability: inbound HL7 v2 ADT^A04 (Register a Patient) messages MUST be ingested
-  through an Interop/Hl7v2 adapter that converts to the RegisterPatientCommand (no direct
-  aggregate writes) over MLLP with ACK handling, and an outbound ADT emitter fires on
-  PatientRegisteredEvent; also expose an external FHIR R4 Patient projection and PIX/PDQ
-  identity cross-reference. Surfaces: internal REST POST /patients returning the created
-  PatientDto with an ETag, the FHIR R4 Patient endpoint, and the HL7 v2 ADT ingress
-  channel. Every PHI read/write must produce an ATNA audit record. Out of scope: patient
-  merge, portal self-registration.
-
-NOTES
-  - The leading `Patient/RegisterPatient` token sets the spec folder; keep PascalCase.
-  - Expect output: SPEC_FILE = specs/Patient/RegisterPatient/spec.md.
-
-
-================================================================================
-STEP 2 — /aw-spec-clarify   (REQUIRED — feature-correctness gate)
-================================================================================
-WHY THIS MATTERS (do not skip)
-  Clarify finds underspecified areas and asks up to 5 targeted questions, then writes the
-  answers back into spec.md. Building plan/tasks/code on an ambiguous spec is the most
-  expensive mistake in the pipeline — for a PHI + HL7 feature the ambiguities have real
-  cost. Resolve at least:
-   - HL7 scope: only ADT^A04, or also A28 (add person) / A31 (update) / A08 (update info)?
-     Which MSH sending/receiving apps? MLLP vs file drop? ACK mode (AA/AE/AR) and NAK on
-     duplicate MRN?
-   - Identity: who assigns the MRN (this system vs source)? PIX/PDQ matching rules and
-     duplicate/merge-candidate handling on inbound ADT.
-   - Consent: is Consent mandatory at registration or optional? purpose-of-use default.
-   - Demographics: required vs optional fields; terminology bindings (administrative sex,
-     marital status); multiple-birth/aliases.
-   - Coverage: required at registration or deferred.
-  Re-run until no high-impact (scope/PHI/interop) ambiguity remains.
-
-CONTEXT FILES TO ADD
-  docs/domainspecs/healthcare/domain-driven-design.domain.md
-  docs/domainspecs/healthcare/hl7.md                          (HL7 ADT clarifications)  <-- HL7
-  docs/domainspecs/healthcare/hipaa.md
-  docs/domainspecs/healthcare/consent.md
-  docs/domainspecs/healthcare/clinical-terms.md
-  docs/domainspecs/healthcare/integration-terms.md
-
-COMMAND
-/aw-spec-clarify @docs/domainspecs/healthcare/domain-driven-design.domain.md @docs/domainspecs/healthcare/hl7.md @docs/domainspecs/healthcare/hipaa.md @docs/domainspecs/healthcare/consent.md @docs/domainspecs/healthcare/clinical-terms.md @docs/domainspecs/healthcare/integration-terms.md
-
-MANUAL TEXT
-  (none — answer the questions it asks; the answers are written back into spec.md)
-
-
-================================================================================
-STEP 3 — /aw-spec-plan   (create the implementation plan / design)
-================================================================================
-PURPOSE
-  Produce plan.md (+ research/data-model/contracts) under specs/Patient/RegisterPatient/.
-  This is where the engineering standards matter most — load the architecture stack,
-  the HL7 adapter rules, and the eventing rules for inbound feeds.
-
-CONTEXT FILES TO ADD
-  Architecture (technology):
-    docs/architecture/folder-structure.md
-    docs/architecture/clean-architecture.md
-    docs/architecture/modular-monolith.md
-    docs/architecture/cqrs.md
-    docs/architecture/vertical-slices.md
-    docs/architecture/persistence.md
-    docs/architecture/eventing.md
-    docs/domainspecs/healthcare/eventing.domain.md       (HL7/FHIR inbound feeds)  <-- HL7
-    docs/architecture/testing.md
-  Domain (healthcare, this slice):
-    docs/domain/domain-driven-design.md
-    docs/domainspecs/healthcare/domain-driven-design.domain.md
-    docs/domainspecs/healthcare/fhir.md
-    docs/domainspecs/healthcare/hl7.md                          (HL7 v2 adapter pattern)  <-- HL7
-    docs/domainspecs/healthcare/dicom.md                        (imaging identifiers; optional for registration)
-    docs/domainspecs/healthcare/terminology.md
-    docs/domainspecs/healthcare/hipaa.md
-    docs/domainspecs/healthcare/consent.md
-  Security:
-    docs/security/authorization.md  + .domain.md
-    docs/security/auditing.md        + .domain.md
-    docs/domainspecs/healthcare/data-classification.domain.md
-  Governance + AI rules:
-    docs/governance/coding-standards.md  + .domain.md
-    docs/glossary/ai-rules.md            + .domain.md
-
-COMMAND (copy-paste, single line)
-/aw-spec-plan Implement RegisterPatient as a complete vertical slice in the Patients module following the loaded standards: Patient aggregate root (Vogen PatientId, MRN value object, HumanName/Address/ContactPoint value objects), RegisterPatientCommand + handler (transaction + PatientRegisteredEvent), SecureFastEndpoint POST /patients with ETag, PatientDto + hand-written ToDto, EF configuration + migration, FHIR R4 Patient projector, and the PHI-access audit behavior. Interop: an Interop/Hl7v2 inbound adapter that parses ADT^A04 and dispatches RegisterPatientCommand via IMediator (no direct aggregate writes), MLLP transport + ACK, and an outbound ADT emitter subscribed to PatientRegisteredEvent; plan PIX/PDQ identity cross-reference. Use AppWeaver.Mediator/Repository/ServiceDefaults per the docs; PostgreSQL prod / SQLite dev; no MediatR/AutoMapper. @docs/architecture/folder-structure.md @docs/architecture/clean-architecture.md @docs/architecture/modular-monolith.md @docs/architecture/cqrs.md @docs/architecture/vertical-slices.md @docs/architecture/persistence.md @docs/architecture/eventing.md @docs/domainspecs/healthcare/eventing.domain.md @docs/architecture/testing.md @docs/domain/domain-driven-design.md @docs/domainspecs/healthcare/domain-driven-design.domain.md @docs/domainspecs/healthcare/fhir.md @docs/domainspecs/healthcare/hl7.md @docs/domainspecs/healthcare/dicom.md @docs/domainspecs/healthcare/terminology.md @docs/domainspecs/healthcare/hipaa.md @docs/domainspecs/healthcare/consent.md @docs/security/authorization.md @docs/domainspecs/healthcare/authorization.domain.md @docs/security/auditing.md @docs/domainspecs/healthcare/auditing.domain.md @docs/domainspecs/healthcare/data-classification.domain.md @docs/governance/coding-standards.md @docs/domainspecs/healthcare/coding-standards.domain.md @docs/glossary/ai-rules.md @docs/domainspecs/healthcare/ai-rules.domain.md
-
-MANUAL TEXT (the prompt portion, for reference)
-  Implement RegisterPatient as a complete vertical slice in the Patients module following
-  the loaded standards: Patient aggregate root (Vogen PatientId, MRN value object,
-  HumanName/Address/ContactPoint value objects), RegisterPatientCommand + handler
-  (transaction + PatientRegisteredEvent), SecureFastEndpoint POST /patients with ETag,
-  PatientDto + hand-written ToDto, EF configuration + migration, FHIR R4 Patient projector,
-  and the PHI-access audit behavior. Interop: an Interop/Hl7v2 inbound adapter that parses
-  ADT^A04 and dispatches RegisterPatientCommand via IMediator (no direct aggregate writes),
-  MLLP transport + ACK, and an outbound ADT emitter subscribed to PatientRegisteredEvent;
-  plan PIX/PDQ identity cross-reference. Use AppWeaver.Mediator/Repository/ServiceDefaults
-  per the docs; PostgreSQL prod / SQLite dev; no MediatR/AutoMapper.
-
-NOTES
-  - No aggregate/feature token here — the folder is resolved from feature.json.
-
-
-================================================================================
-STEP 4 — /aw-spec-tasks   (generate the dependency-ordered task list)
-================================================================================
-PURPOSE
-  Produce tasks.md from plan.md under specs/Patient/RegisterPatient/.
-
-CONTEXT FILES TO ADD
-  docs/architecture/folder-structure.md
-  docs/architecture/vertical-slices.md   (+ .domain.md)
-  docs/architecture/cqrs.md               (+ .domain.md)
-  docs/architecture/persistence.md        (+ .domain.md)
-  docs/architecture/testing.md            (+ .domain.md)
-  docs/architecture/eventing.md           (+ .domain.md)
-  docs/domainspecs/healthcare/domain-driven-design.domain.md
-  docs/domainspecs/healthcare/fhir.md
-  docs/domainspecs/healthcare/hl7.md                       (HL7 adapter tasks)  <-- HL7
-  docs/security/authorization.md          (+ .domain.md)
-  docs/security/auditing.md               (+ .domain.md)
-  docs/governance/coding-standards.md     (+ .domain.md)
-  docs/glossary/ai-rules.md               (+ .domain.md)
-
-COMMAND (copy-paste, single line)
-/aw-spec-tasks Break the plan into ordered, testable tasks for the RegisterPatient slice: value objects + tests, Patient aggregate + invariant tests, EF config + migration, RegisterPatientCommand/Validator/Handler + handler tests (happy/validation/not-found/conflict), SecureFastEndpoint + integration test, FHIR Patient projector + round-trip test, HL7 v2 ADT^A04 inbound parser + outbound emitter with HL7 conformance tests against an internal corpus, PatientRegisteredEvent + publish, PHI-audit wiring. Tests precede implementation. @docs/architecture/folder-structure.md @docs/architecture/vertical-slices.md @docs/domainspecs/healthcare/vertical-slices.domain.md @docs/architecture/cqrs.md @docs/domainspecs/healthcare/cqrs.domain.md @docs/architecture/persistence.md @docs/domainspecs/healthcare/persistence.domain.md @docs/architecture/testing.md @docs/domainspecs/healthcare/testing.domain.md @docs/architecture/eventing.md @docs/domainspecs/healthcare/eventing.domain.md @docs/domainspecs/healthcare/domain-driven-design.domain.md @docs/domainspecs/healthcare/fhir.md @docs/domainspecs/healthcare/hl7.md @docs/security/authorization.md @docs/domainspecs/healthcare/authorization.domain.md @docs/security/auditing.md @docs/domainspecs/healthcare/auditing.domain.md @docs/governance/coding-standards.md @docs/domainspecs/healthcare/coding-standards.domain.md @docs/glossary/ai-rules.md @docs/domainspecs/healthcare/ai-rules.domain.md
-
-MANUAL TEXT (the prompt portion, for reference)
-  Break the plan into ordered, testable tasks for the RegisterPatient slice: value objects
-  + tests, Patient aggregate + invariant tests, EF config + migration,
-  RegisterPatientCommand/Validator/Handler + handler tests
-  (happy/validation/not-found/conflict), SecureFastEndpoint + integration test, FHIR
-  Patient projector + round-trip test, HL7 v2 ADT^A04 inbound parser + outbound emitter
-  with HL7 conformance tests against an internal corpus, PatientRegisteredEvent + publish,
-  PHI-audit wiring. Tests precede implementation.
-
-
-================================================================================
-STEP 5 — /aw-spec-analyze   (REQUIRED — cross-artifact correctness gate)
-================================================================================
-WHY THIS MATTERS (do not skip)
-  Analyze is a non-destructive consistency/quality check across spec.md, plan.md, and
-  tasks.md, run AFTER tasks and BEFORE implement. It is the last gate before code, and for
-  a regulated, interoperable feature it catches exactly the failures that are most costly
-  after implementation:
-   - Requirements in the spec with no covering task (e.g. ADT^A04 ingest, PIX/PDQ, Consent
-     capture, audit on every PHI write).
-   - Tasks with no basis in the spec (scope creep).
-   - Constitution NON-NEGOTIABLE gaps: missing ATNA audit task, hard-delete instead of
-     soft-delete, missing ETag/If-Match concurrency, PHI in logs, free-text where a coded
-     value object is required, a second FHIR write path, banned packages.
-   - Terminology / naming drift between artifacts.
-  Fix everything it flags by amending spec/plan/tasks, then re-run until clean.
-
-CONTEXT FILES TO ADD
-  docs/domainspecs/healthcare/hl7.md                       (verify HL7 coverage)  <-- HL7
-  docs/domainspecs/healthcare/hipaa.md
-  docs/domainspecs/healthcare/auditing.domain.md
-  docs/governance/coding-standards.md     (+ .domain.md)
-  docs/domainspecs/healthcare/ai-rules.domain.md
-
-COMMAND
-/aw-spec-analyze @docs/domainspecs/healthcare/hl7.md @docs/domainspecs/healthcare/hipaa.md @docs/domainspecs/healthcare/auditing.domain.md @docs/governance/coding-standards.md @docs/domainspecs/healthcare/coding-standards.domain.md @docs/domainspecs/healthcare/ai-rules.domain.md
-
-MANUAL TEXT
-  (none — review the report, then amend spec/plan/tasks for any finding and re-run)
-
-
-================================================================================
-STEP 6 — /aw-spec-implement   (execute the tasks / write the code)
-================================================================================
-PURPOSE
-  Execute tasks.md and produce the actual source under src/ following the standards.
-  Add the full implementation context: tasks-set + HL7 + dependency/versioning +
-  FHIR/terminology + data-classification/zero-trust.
-
-CONTEXT FILES TO ADD
-  (everything from STEP 4) PLUS:
-    docs/domainspecs/healthcare/hl7.md                      (already in step 4 — keep)  <-- HL7
-    docs/governance/dependency-policy.md   (+ .domain.md)
-    docs/governance/api-versioning.md      (+ .domain.md)
-    docs/domainspecs/healthcare/terminology.md
-    docs/security/data-classification.md    (+ .domain.md)
-    docs/security/zero-trust.md             (+ .domain.md)
-
-COMMAND (copy-paste, single line)
-/aw-spec-implement Implement the RegisterPatient tasks exactly per the loaded standards. Generate the complete vertical slice (Domain/Persistence/Features/Shared), the Interop/Hl7v2 ADT^A04 inbound adapter + outbound ADT emitter (MLLP + ACK, no direct aggregate writes), the FHIR R4 Patient projector, unit + integration + FHIR-validator + HL7-conformance tests, and the EF migration. Honor every NON-NEGOTIABLE: Result pattern, ETag/If-Match concurrency, soft-delete, ATNA audit, minimum-necessary, no PHI in logs, coded value objects, inbound feeds via adapters only, no banned packages. Do not run migrations against shared environments. @docs/architecture/folder-structure.md @docs/architecture/vertical-slices.md @docs/domainspecs/healthcare/vertical-slices.domain.md @docs/architecture/cqrs.md @docs/domainspecs/healthcare/cqrs.domain.md @docs/architecture/persistence.md @docs/domainspecs/healthcare/persistence.domain.md @docs/architecture/testing.md @docs/domainspecs/healthcare/testing.domain.md @docs/architecture/eventing.md @docs/domainspecs/healthcare/eventing.domain.md @docs/domain/domain-driven-design.md @docs/domainspecs/healthcare/domain-driven-design.domain.md @docs/domainspecs/healthcare/fhir.md @docs/domainspecs/healthcare/hl7.md @docs/domainspecs/healthcare/terminology.md @docs/domainspecs/healthcare/hipaa.md @docs/domainspecs/healthcare/consent.md @docs/security/authorization.md @docs/domainspecs/healthcare/authorization.domain.md @docs/security/auditing.md @docs/domainspecs/healthcare/auditing.domain.md @docs/security/data-classification.md @docs/domainspecs/healthcare/data-classification.domain.md @docs/security/zero-trust.md @docs/domainspecs/healthcare/zero-trust.domain.md @docs/governance/coding-standards.md @docs/domainspecs/healthcare/coding-standards.domain.md @docs/governance/dependency-policy.md @docs/domainspecs/healthcare/dependency-policy.domain.md @docs/governance/api-versioning.md @docs/domainspecs/healthcare/api-versioning.domain.md @docs/glossary/ai-rules.md @docs/domainspecs/healthcare/ai-rules.domain.md
-
-MANUAL TEXT (the prompt portion, for reference)
-  Implement the RegisterPatient tasks exactly per the loaded standards. Generate the
-  complete vertical slice (Domain/Persistence/Features/Shared), the Interop/Hl7v2 ADT^A04
-  inbound adapter + outbound ADT emitter (MLLP + ACK, no direct aggregate writes), the
-  FHIR R4 Patient projector, unit + integration + FHIR-validator + HL7-conformance tests,
-  and the EF migration. Honor every NON-NEGOTIABLE: Result pattern, ETag/If-Match
-  concurrency, soft-delete, ATNA audit, minimum-necessary, no PHI in logs, coded value
-  objects, inbound feeds via adapters only, no banned packages. Do not run migrations
-  against shared environments.
-
-
-================================================================================
-QUICK REFERENCE — order of operations (all required for this feature)
-================================================================================
-  (0) /aw-spec-select-domain  ... one-time: set active domain (healthcare) -> .aw-spec/domain.json
- (0b) /aw-spec-constitution   ... one-time, if not yet ratified
-   1. /aw-spec-specify        ... Patient/RegisterPatient + domain/glossary + HL7 context
-   2. /aw-spec-clarify        ... correctness gate: resolve HL7/PHI/identity ambiguities
-   3. /aw-spec-plan           ... architecture + domain + HL7/eventing + security + governance
-   4. /aw-spec-tasks          ... tasks-set + HL7 adapter/conformance tasks
-   5. /aw-spec-analyze        ... correctness gate: spec<->plan<->tasks + NON-NEGOTIABLE coverage
-   6. /aw-spec-implement      ... full build: slice + HL7 adapters + FHIR + tests + migration
-
-All steps after /aw-spec-specify auto-resolve specs/Patient/RegisterPatient/ from
-.aw-spec/feature.json — do not repeat the Patient/RegisterPatient token.
-
-HL7 v2 is threaded through every step (docs/domainspecs/healthcare/hl7.md + docs/domainspecs/healthcare/eventing.domain.md) because inbound
-ADT^A04 ingestion and outbound ADT emission are first-class surfaces of this feature, not an
-afterthought — interoperability is a NON-NEGOTIABLE constitution principle (XIV).

package/assets/docs/components/Email/README.md

@@ -1,119 +0,0 @@
-# Email Component (`AppWeaver.Messaging.Email`)
-
-> Pure technology (domain-agnostic). Reference sheet for the Email messaging component.
-> To wire it into a project, follow the agent runbook in [integration.md](./integration.md).
-> Commands: `/aw-spec-plan`, `/aw-spec-tasks`, `/aw-spec-implement`.
-
-## What it is
-
-A provider-agnostic email-sending component. Application code depends on a single abstraction,
-`IEmailService`; the transport (Microsoft Graph, SMTP, SendGrid, OAuth2-SMTP, or a local File
-sink) is chosen once during DI registration via `AddEmailMessaging(...)`.
-
-**Use when:** a feature must send transactional or notification email (user-created alerts,
-confirmations, admin notices, password flows, attachments).
-
-## Public contract (`AppWeaver.Messaging.Email`)
-
-```csharp
-namespace AppWeaver.Messaging.Email;
-
-public interface IEmailService
-{
-    // Convenience overload — single recipient.
-    Task SendAsync(string from, string to, string subject, string body,
-                   bool isHtml = true, CancellationToken cancellationToken = default);
-
-    // Full message — multi-recipient, Cc/Bcc, attachments.
-    Task SendAsync(EmailMessage message, CancellationToken cancellationToken = default);
-}
-```
-
-```csharp
-namespace AppWeaver.Messaging.Email.Entities;
-
-public class EmailMessage
-{
-    public string From { get; set; }                 // falls back to provider DefaultFrom if empty
-    public List<string> To { get; set; }  = new();
-    public List<string> Cc { get; set; }  = new();
-    public List<string> Bcc { get; set; } = new();
-    public string Subject { get; set; }
-    public string Body { get; set; }
-    public bool IsHtml { get; set; } = true;
-    public List<EmailAttachment> Attachments { get; set; } = new();
-}
-
-public class EmailAttachment
-{
-    public string FileName { get; set; }
-    public byte[] Content { get; set; }
-    public string ContentType { get; set; } = "application/octet-stream";
-}
-```
-
-## Packages
-
-| Package | Version | Role | Builder method | Provider key |
-|---|---|---|---|---|
-| `AppWeaver.Messaging.Email` | `0.1.3` | **Required.** Abstraction + `AddEmailMessaging` + facade. | — | — |
-| `AppWeaver.Messaging.Email.MsGraph` | `0.1.2` | Microsoft 365 / Graph API (recommended for prod). | `UseMsGraph` | `MsGraph` |
-| `AppWeaver.Messaging.Email.Smtp` | `0.1.3` | Classic SMTP (host/port/user/password). | `UseSmtp` | `Smtp` |
-| `AppWeaver.Messaging.Email.SendGrid` | `0.1.2` | SendGrid API key. | `UseSendGrid` | `SendGrid` |
-| `AppWeaver.Messaging.Email.OAuth2` | `0.1.3` | OAuth2-authenticated SMTP (O365). | `UseOAuth2` | `OAuth2` |
-| `AppWeaver.Messaging.Email.File` | `0.1.2` | Writes email to a local `.txt` file — local dev / tests. | `UseFile` | `File` |
-
-Install the abstraction **plus exactly one provider** for the environment you are wiring.
-
-## Provider option shapes
-
-| Provider | Options type | Key fields | Bound config section |
-|---|---|---|---|
-| MsGraph | `MsGraphEmailOptions` | `TenantId`, `ClientId`, `ClientSecret`, `DefaultFrom`, `Scopes` | `Messaging.Email.MsGraph` |
-| Smtp | `SmtpEmailOptions` | `Host`, `Port`, `Username`, `Password`, `EnableSsl`, `DefaultFrom` | `Messaging.Email.Smtp` |
-| SendGrid | `SendGridEmailOptions` | `ApiKey` *(required)*, `DefaultFrom` | `Messaging.Email.SendGrid` |
-| OAuth2 | `OAuth2EmailOptions` | `TenantId`, `ClientId`, `ClientSecret`, `Host`, `Port`, `Scopes`, `DefaultFrom` | `Messaging.Email.OAuth2` |
-| File | `FileEmailOptions` | `DefaultFrom` | `Messaging.Email.Smtp` *(quirk — pass options inline)* |
-
-## Registration entry point
-
-```csharp
-// In AppWeaver.Messaging.Email.Extensions
-IComponentBuilder<IEmailService> AddEmailMessaging(
-    this IServiceCollection services,
-    Action<IComponentBuilder<IEmailService>> configureBuilder,   // required
-    Action<MessagingEmailConfiguration>? configureOptions = null,// set Provider here
-    IConfiguration? configuration = null);                       // OR bind from config
-```
-
-`MessagingEmailConfiguration` exposes a single `[Required] string Provider`. The facade
-(`DefaultImplementation`) resolves the keyed provider whose key equals `Provider`.
-
-## Source map (framework)
-
-```
-framework/Messaging.Email/
-  Integration.md                         ← original MsGraph tutorial (reference)
-  src/
-    AppWeaver.Messaging.Email/           ← IEmailService, EmailMessage, AddEmailMessaging, facade
-    AppWeaver.Messaging.Email.MsGraph/   ← UseMsGraph + MsGraphEmailService
-    AppWeaver.Messaging.Email.Smtp/      ← UseSmtp + SmtpEmailService
-    AppWeaver.Messaging.Email.SendGrid/  ← UseSendGrid + SendGridEmailService
-    AppWeaver.Messaging.Email.OAuth2/    ← UseOAuth2 + OAuth2EmailService
-    AppWeaver.Messaging.Email.File/      ← UseFile  + FileEmailService
-  test/
-    MsGraphTest/Program.cs               ← MsGraph end-to-end sample
-    TestApp/Program.cs                   ← OAuth2 + File multi-provider sample
-```
-
-## Sample reference endpoint
-
-A ready-to-run FastEndpoint that sends mail inline (no command/handler) is bundled at
-[`ReferenceEndpoints/SendEmailEndpoint.cs`](./ReferenceEndpoints/SendEmailEndpoint.cs). It is offered
-(opt-in) at the end of the [integration.md](./integration.md) runbook and, if accepted, copied into
-the host project's `ReferenceEndpoints/` folder. Endpoint: `POST /reference/email/send`.
-
-## Related
-
-- [integration.md](./integration.md) · [[components-readme]] · [[cqrs]] ·
-  [[clean-architecture]] · [[dependency-policy]]

package/assets/docs/components/Email/ReferenceEndpoints/SendEmailEndpoint.cs

@@ -1,84 +0,0 @@
-using FastEndpoints;
-using Microsoft.Extensions.Configuration;
-using AppWeaver.Messaging.Email;
-
-// NOTE: This is a bundled SAMPLE endpoint for the AppWeaver Email component.
-// It lives under docs/ and is NOT compiled here. /aw-spec-addcomponent copies it into the
-// host project's ReferenceEndpoints/ folder and replaces the __HOSTPROJECT__ namespace token
-// with the host project's root namespace (e.g. AppWeaver.Health.Service).
-namespace __HOSTPROJECT__.ReferenceEndpoints;
-
-/// <summary>
-/// Sample reference endpoint for the AppWeaver Email component.
-///
-/// Demonstrates the full send sequence inline — it injects the <see cref="IEmailService"/>
-/// abstraction directly and calls <c>SendAsync</c> with the provider wired during DI
-/// registration (see the component's integration runbook). There is intentionally no
-/// command / command-handler / mediator: this is a copy-paste sample only.
-///
-/// The active transport is whatever <c>options.Provider</c> was set to when
-/// <c>AddEmailMessaging(...)</c> was registered. With the <c>File</c> provider the message is
-/// written to <c>Emails_&lt;yyyy-MM-dd&gt;.txt</c> in the application base directory.
-/// </summary>
-public class SendEmailEndpoint(IEmailService _email, IConfiguration _config)
-    : Endpoint<SendEmailRequest>
-{
-    public override void Configure()
-    {
-        Post("/reference/email/send");
-        AllowAnonymous();
-        Summary(s =>
-        {
-            s.Summary = "Send a sample email via the configured Email provider";
-            s.Description = "Reference endpoint for the AppWeaver Email component. Injects "
-                          + "IEmailService directly (no command/handler). 'from' falls back to "
-                          + "Messaging:Email:DefaultFrom when omitted.";
-        });
-        Options(o => o.WithTags("Reference - Email"));
-    }
-
-    public override async Task HandleAsync(SendEmailRequest req, CancellationToken ct)
-    {
-        if (string.IsNullOrWhiteSpace(req.To) || string.IsNullOrWhiteSpace(req.Subject))
-        {
-            HttpContext.Response.StatusCode = 400;
-            await HttpContext.Response.WriteAsJsonAsync(
-                new { error = "'to' and 'subject' are required." }, ct);
-            return;
-        }
-
-        // 'from' is optional in the request — fall back to the configured DefaultFrom.
-        var from = string.IsNullOrWhiteSpace(req.From)
-            ? _config["Messaging:Email:DefaultFrom"] ?? "no-reply@your-domain.com"
-            : req.From;
-
-        await _email.SendAsync(from, req.To, req.Subject, req.Body ?? string.Empty, req.IsHtml, ct);
-
-        await HttpContext.Response.WriteAsJsonAsync(new
-        {
-            status = "sent",
-            from,
-            to = req.To,
-            note = "With the File provider, output is written to Emails_<yyyy-MM-dd>.txt "
-                 + "in the app base directory."
-        }, ct);
-    }
-}
-
-public class SendEmailRequest
-{
-    /// <summary>Recipient address (required).</summary>
-    public string To { get; set; } = string.Empty;
-
-    /// <summary>Subject line (required).</summary>
-    public string Subject { get; set; } = string.Empty;
-
-    /// <summary>HTML or plain-text body.</summary>
-    public string Body { get; set; } = string.Empty;
-
-    /// <summary>Treat <see cref="Body"/> as HTML. Defaults to true.</summary>
-    public bool IsHtml { get; set; } = true;
-
-    /// <summary>Optional sender; falls back to Messaging:Email:DefaultFrom when omitted.</summary>
-    public string? From { get; set; }
-}