aw-spec-cli 0.1.5 → 0.1.7

package/assets/.aw-spec/templates/spec-template.md

@@ -1,252 +0,0 @@
-# Specification: [AGGREGATE]
-
-**Aggregate (feature)**: `[Aggregate]`  <!-- the feature = the aggregate, e.g. Order -->
-
-**Spec home**: `specs/[Aggregate]/`
-
-**Version**: v1.0   <!-- living truth; every applied change request bumps this — see Change History -->
-
-**Status**: Draft
-
-**Input**: User description: "$ARGUMENTS"
-
-<!--
-  AGGREGATE = FEATURE. This spec covers ONE aggregate (e.g. Order) and is the
-  single LIVING source of truth for its whole lifecycle. Every operation on it
-  (CreateOrder, UpdateOrder, …) is a USER STORY below — NOT a separate feature.
-  A later requirement is a new US-n added here as a delta (see .aw-spec/changes/
-  and delta-spec-template.md), never a new spec folder. One spec + one design.md
-  (specs/[Aggregate]/design.md) — the DESIGN derives from THIS document.
-
-  Section order is intentional: establish the business need and scope, then the
-  stable core the aggregate IS (requirements → rules → constraints → entities →
-  data classification → integration contracts → edge cases), then the prioritized
-  user journeys that exercise it, then measurable success.
-
-  DOMAIN LIFT (specify's job): three sections — Constraints & NFRs (CN-), Data
-  Classification (DC-), Integration Contracts (IC-) — are where specify LIFTS
-  domain-derived constraints out of the domain rule files into the spec. Design
-  authors architecture from the spec ONLY, so anything not captured here never
-  reaches design. Fill them when the domain applies; keep them (empty → "None")
-  otherwise.
--->
-
-## Business Need
-
-<!--
-  ACTION REQUIRED: Why this aggregate exists — the problem, the affected users,
-  and the value delivered. Business-facing; no implementation detail.
--->
-
-[The problem this aggregate solves, who it serves, and the value it delivers.]
-
-## Scope & Assumptions
-
-### Aggregate Boundary
-
-<!--
-  The aggregate = the largest slice whose code no other feature owns. State what
-  it OWNS, what it only REFERENCES (by identifier, not owned), and what is out of
-  scope. This anchors the design's "dependencies point inward" and keeps commands
-  as deltas on THIS aggregate rather than new features.
--->
-
-- **Owns**: [entities/behaviour inside this aggregate — e.g. Order, OrderLine]
-- **References (by id, not owned)**: [Customer, Product — read-only / by identifier]
-- **Out of scope / non-goals**: [explicitly excluded — e.g. payment settlement, shipping]
-
-### Assumptions
-
-<!--
-  Reasonable defaults chosen where the description was silent, plus dependencies
-  on existing systems/services.
--->
-
-- [Assumption about target users, e.g., "Users have stable internet connectivity"]
-- [Assumption about scope, e.g., "Mobile support is out of scope for v1"]
-- [Dependency on an existing system/service, e.g., "Requires the existing user-profile API"]
-
-## System Requirements *(mandatory)*
-
-<!--
-  Functional requirements in EARS notation (Easy Approach to Requirements Syntax):
-  atomic, testable, unambiguous. Choose the pattern that fits each requirement —
-
-    • Ubiquitous     THE SYSTEM SHALL <requirement>
-    • Event-driven   WHEN <trigger> THE SYSTEM SHALL <response>
-    • State-driven   WHILE <in a state> THE SYSTEM SHALL <response>
-    • Unwanted       IF <condition/error> THEN THE SYSTEM SHALL <response>
-    • Optional       WHERE <feature is present> THE SYSTEM SHALL <response>
-
-  Give each a STABLE id (FR-001, …) — design sections and code trace to these ids.
-  Mark genuine unknowns "[NEEDS CLARIFICATION: <question>]" (≤3; scope/UX/security
-  only, and only where no reasonable default exists).
--->
-
-- **FR-001**: WHEN [a customer submits an order] THE SYSTEM SHALL [create it in Draft state].
-- **FR-002**: THE SYSTEM SHALL [persist every order under a unique identifier].
-- **FR-003**: IF [the order has no line items] THEN THE SYSTEM SHALL [reject the submission].
-- **FR-004**: WHILE [an order is in Draft] THE SYSTEM SHALL [allow line items to be added or removed].
-- **FR-005**: WHERE [tax calculation is enabled] THE SYSTEM SHALL [apply the regional tax rule].
-
-## Business Rules *(invariants — always true, technology-agnostic)*
-
-<!--
-  ACTION REQUIRED: Constraints that must ALWAYS hold for the aggregate, independent
-  of any single operation. These become the design's §Domain invariants and must be
-  enforceable and testable. Give each a STABLE id (BR-001, …).
--->
-
-- **BR-001**: [An order's total MUST never be negative.]
-- **BR-002**: [A submitted order MUST always have at least one line item.]
-- **BR-003**: [An order's identifier is immutable once created.]
-
-## Constraints & Non-Functional Requirements *(domain lift — CN)*
-
-<!--
-  ACTION REQUIRED (when the domain applies; else "None (as of vX.Y)"). Constraints the
-  aggregate MUST satisfy that are NEITHER functional behaviour (those are FR) NOR
-  always-true business invariants (those are BR): the regulatory, retention,
-  immutability, audit-mandate, and performance-as-a-limit rules. Many are LIFTED here
-  by specify from the domain rule files (e.g. persistence.domain, auditing.domain,
-  data-classification.domain) so they survive into design — which reads the spec ONLY.
-  Give each a STABLE id (CN-001, …); design's §5 Cross-Cutting and the analyze gate
-  trace to these ids. State each as testable; where lifted, cite the source rule.
--->
-
-- **CN-001**: [Retention — e.g. submitted orders + their audit trail are retained for [period] per [policy]; hard delete is forbidden once submitted (logical/retire only). — lifted from persistence.domain]
-- **CN-002**: [Audit immutability — e.g. every create/modify/cancel emits an append-only audit entry (User, Timestamp, Action, Previous, New). — lifted from auditing.domain]
-- **CN-003**: [Data integrity — e.g. records subject to [regime] satisfy [integrity standard].]
-- **CN-004**: [Performance-as-a-limit — e.g. P95 read latency < 200 ms at 200 RPS; not a behaviour, a bound.]
-
-## Key Entities *(the aggregate's conceptual model — no implementation detail)*
-
-<!--
-  The aggregate root and the entities/value objects inside its boundary: what each
-  represents, its key attributes, lifecycle/states, and relationships. Reference to
-  OTHER aggregates is by identifier only (see Aggregate Boundary).
--->
-
-- **[Aggregate root — e.g. Order]**: [what it represents; key attributes; lifecycle/states, e.g. Draft → Submitted → Fulfilled]
-- **[Entity / value object — e.g. OrderLine]**: [what it represents; relationship to the root]
-
-## Data Classification *(domain lift — DC)*
-
-<!--
-  ACTION REQUIRED (when the aggregate handles sensitive data; else "None (as of vX.Y)").
-  The sensitivity taxonomy for this aggregate's data and the exposure rules that follow:
-  which categories exist, which Key-Entity fields fall in each, and where each category
-  MAY / MUST NOT appear (public API surface, logs, metrics, traces, external projections).
-  Lifted by specify from the domain data-classification rules. Design enforces these; the
-  analyze-design / analyze-slice gates check them. Give each a STABLE id (DC-001, …); reference fields by
-  the names used in Key Entities.
--->
-
-| id | Category | Applies to (fields / entities) | Exposure rule |
-|---|---|---|---|
-| DC-001 | [Public] | [id, status, non-sensitive attributes] | [may appear on the public API + external projections] |
-| DC-002 | [Sensitive / restricted] | [PII, pre-release, commercially-sensitive fields] | [MUST NOT appear on the public surface, nor in logs / metrics / traces] |
-| DC-003 | [Externally-sourced] | [imported fields] | [carries provenance; [handling rule]] |
-
-## Integration Contracts *(domain lift — IC)*
-
-<!--
-  ACTION REQUIRED (when the aggregate interoperates; else "None (as of vX.Y)"). The
-  external contracts this aggregate MUST satisfy — interoperability obligations lifted by
-  specify from the domain interop rules (e.g. FHIR/HL7/DICOM projections, terminology
-  services, inbound feeds). State each at CONTRACT level: which standard, which resources,
-  direction (inbound/outbound), projection vs system-of-record — NOT the adapter design
-  (design realises these in its API / Infrastructure layers). Give each a STABLE id
-  (IC-001, …); design's §4.2 External Integrations traces to these ids.
--->
-
-- **IC-001**: [Outbound projection — e.g. the aggregate SHALL project to [external standard / resources] as read-only projections (not the system of record); identifiers map to [external identifier]; coded fields to [coded type].]
-- **IC-002**: [Reference-data validation — e.g. coded values SHALL validate against [terminology / reference service]; no invented codes.]
-- **IC-003**: [Inbound feed — e.g. inbound [feed/standard] SHALL flow through an Interop adapter, never a direct write path to the aggregate.]
-
-## Edge Cases & Exceptional Scenarios
-
-<!--
-  ACTION REQUIRED: Boundary conditions, error paths, and concurrency/consistency
-  cases. Each should map to a System Requirement (often an IF…THEN unwanted-behaviour
-  requirement) or a Business Rule.
--->
-
-- What happens when [boundary condition, e.g., the same order is submitted twice]?
-- How does the system handle [error scenario, e.g., a referenced product no longer exists]?
-
-## User Stories *(prioritized)*
-
-<!--
-  Prioritized user journeys (P1 = most critical). Each MUST be INDEPENDENTLY
-  TESTABLE — implementing just one still yields a viable slice of value that can be
-  developed, tested, deployed, and demonstrated on its own.
-
-  Give each a STABLE id (US-1, US-2, …); design sections trace to these ids. Each
-  story exercises specific System Requirements / Business Rules — cite them so the
-  spine (US ↔ FR/BR ↔ design ↔ code) stays exact. On this living spec, note when a
-  story entered or changed: "Added: vX.Y (CR-…)" / "Modified: vX.Y (CR-…)".
--->
-
-### US-1 - [Brief Title] (Priority: P1)   ·   _Added: v1.0_
-
-[Describe this user journey in plain language.]
-
-**Why this priority**: [The value and why it ranks here.]
-
-**Exercises**: [FR-001, FR-003, BR-001]
-
-**Acceptance Criteria**:
-
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
-2. **Given** [initial state], **When** [action], **Then** [expected outcome]
-
-**Independent Test**: [How this story is verified on its own and the value it delivers.]
-
----
-
-### US-2 - [Brief Title] (Priority: P2)   ·   _Added: v1.0_
-
-[Describe this user journey in plain language.]
-
-**Why this priority**: [The value and why it ranks here.]
-
-**Exercises**: [FR-…, BR-…]
-
-**Acceptance Criteria**:
-
-1. **Given** [initial state], **When** [action], **Then** [expected outcome]
-
-**Independent Test**: [How this story is verified on its own.]
-
----
-
-[Add more user stories as needed (US-3, US-4, …), each with a priority and a stable id.]
-
-## Success Criteria *(mandatory)*
-
-<!--
-  ACTION REQUIRED: Measurable, technology-agnostic outcomes — verified at the
-  `analyze-slice` phase. Give each a STABLE id (SC-001, …).
--->
-
-### Measurable Outcomes
-
-- **SC-001**: [Measurable metric, e.g., "A customer can place an order in under 2 minutes."]
-- **SC-002**: [Measurable metric, e.g., "The system sustains 1000 concurrent orders without degradation."]
-- **SC-003**: [User-satisfaction metric, e.g., "90% of first-time users complete an order without assistance."]
-- **SC-004**: [Business metric, e.g., "Reduce order-related support tickets by 50%."]
-
-## Change History
-
-<!--
-  The living-truth ledger. Every applied change request appends a row here, carrying
-  the version it ships as. finalize-delta writes the row when it merges the delta;
-  close-delta then archives the CR, bumps the minor version in active_version.json and
-  stamps that same number into this document's **Version** header — one mechanism, one
-  stage, so header, row and active_version.json never disagree. Newest last.
--->
-
-| Version | Date | Change | User stories | CR |
-|---------|------|--------|--------------|-----|
-| v1.0 | [DATE] | Initial specification | US-1 | — |