aw-spec-cli 0.1.8 → 0.1.9

package/assets/guardrails/technology/nextjs/forms-and-validation.md

@@ -0,0 +1,75 @@
+# Forms & Validation Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE where marked.
+> Commands: `/aw-spec-design-ui`, `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-V (every interaction state is specified) and
+> UX-VII (mutations flow through one path).
+
+A form is where the three failure modes meet — a user making mistakes, a network that may
+not answer, and a service that is the real authority. All three are designed, not
+discovered.
+
+## The authority rule (NON-NEGOTIABLE)
+
+- **A client-side check restates a service rule for feedback. It NEVER replaces it.** The
+  service's validators check request shape and its domain enforces the invariants
+  ([[api-integration.<service-stack>]]).
+- Every client-side rule **cites the spec id it echoes** (`BR-`/`FR-`) in the design's §4 and
+  in a code comment. An uncited client rule is a second, drifting copy of a business rule.
+- A rule the service enforces and the client cannot know — uniqueness, cross-record limits,
+  state transitions — is **not** guessed at client-side. The form submits and renders the
+  service's field errors.
+
+## What the design owns
+
+`design.ui.md §4` states, per form:
+
+- **When validation runs** per field group — on change, on blur, on submit. Validating a
+  required field on first keystroke tells the user they are wrong before they have finished
+  being right.
+- **How failures are surfaced** — inline per field, summarised at the top, or both — and
+  where focus goes on failure.
+- **What is disabled while in flight**, and what a second submit does.
+- **What happens on cancel and on navigate-away** with unsaved changes.
+- **What survives a failed submit** — the user's input always does; a form that clears
+  itself on a server error is data loss.
+
+## Field errors from the service
+
+- A `400` carries field-level errors. They are mapped onto the matching fields, not shown as
+  one opaque banner.
+- A field error the client cannot attribute to a field is surfaced at form level, never
+  dropped.
+- Focus moves to the first offending field, and the error is programmatically associated
+  with it so it is announced ([[accessibility-implementation]]).
+
+## Submission
+
+- The submit path is the one mutation path (UX-VII): a Server Action or a generated-client
+  wrapper, never an ad-hoc handler.
+- **Double submit is prevented in the UI and safe at the service.** The control disables on
+  submit, and the operation is idempotent or carries a client-generated key — because the
+  disable can be bypassed.
+- On success the form's invalidation runs ([[state-management]]) and the design's success
+  state renders. "The call returned 2xx" is not, by itself, a state the user sees.
+- On a `409` version conflict the stale-record state renders — never an automatic retry
+  ([[api-integration.<service-stack>]]).
+
+## Input handling
+
+- Input is trimmed, normalised and typed at the client boundary, once — not in each
+  consumer.
+- Numeric, date and currency input is parsed against the active locale ([[i18n]]) and sent
+  in the contract's canonical form. A date sent in the browser's local interpretation is a
+  timezone bug waiting for a user in another country.
+- Classified fields are not autocompleted, not autofilled into unrelated fields and not
+  echoed into the URL ([[client-security]]).
+- Destructive actions are confirmed as the design specifies, and the confirmation names what
+  will happen — including that a delete is a **logical** delete where the service does one.
+
+## Related
+
+- [[error-handling]] — the five states every submission passes through
+- [[api-integration.<service-stack>]] — the service's validation and conflict contract
+- [[accessibility-implementation]] — label association, announcement, focus
+- [[i18n]] — locale-aware parsing and formatting

package/assets/guardrails/technology/nextjs/frontend-testing.md

@@ -0,0 +1,94 @@
+# Frontend Testing Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE.
+> Commands: `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-XI (frontend test-first).
+
+Every file `implement-ui` generates ships with its test. The design says what to test: each
+test **cites the spec id** from `design.ui.md §7 Traceability` that it covers, so a coverage
+gap reads as a `UX-`/`US-`/`FR-` with no test rather than as a percentage.
+
+## What ships with what
+
+| Generated | Test that ships with it |
+|---|---|
+| Screen | renders for each of its `§1` access conditions; the not-found and denied paths |
+| Feature component | its stated responsibility, its inputs at their boundaries, the events it raises |
+| Form | validation timing, the field-error mapping, the double-submit guard, what survives a failed submit |
+| Client-layer wrapper | contract integration against the **generated types**, including the failure mapping |
+| Every interactive surface | an accessibility assertion |
+
+## The interaction states ARE the coverage
+
+Per UX-V and `§4`, loading, empty, error, permission-denied and in-flight each get a test.
+These are the assertions that catch real regressions; a suite covering only the happy path
+passes while the surface is broken. Specifically:
+
+- **Empty is distinct from loading**, and both are asserted — a spinner that never resolves
+  and a genuinely empty list look identical to a test that only checks "no rows".
+- **`403` renders denied, not error.** A test that accepts any failure state cannot tell
+  them apart, and neither will the user.
+- **A `409` version conflict renders the stale-record state and does NOT retry.** Assert
+  the absence of the retry ([[api-integration.<service-stack>]]).
+- **Out-of-range paging** — an empty item list with a non-zero total — renders the
+  past-the-last-page state, distinct from "no results".
+- A retryable failure retries a bounded number of times; a non-idempotent mutation does not
+  retry at all.
+
+## Testing through the user's surface
+
+- Query by **role, accessible name and visible text**. A test coupled to an internal
+  structure fails on a refactor that changed nothing a user can see, and passes when the
+  accessible name is wrong.
+- **A snapshot is not coverage.** It records what the code does, including what it does
+  wrong, and it is approved by whoever is least likely to read it.
+- Assert on outcomes, not on implementation calls. "The mutation wrapper was called" is
+  weaker than "the row disappears and the toast names the record".
+
+## Contract integration
+
+- The service is stubbed **at the client layer**, against the generated contract types. A
+  stub that does not typecheck against the contract is a test asserting a contract that does
+  not exist ([[api-client]]).
+- Stubs mirror the **real** shapes the pairing file states — the paged envelope with its
+  actual field names, the version token on tracked reads, the real error codes. A
+  hand-written happy shape hides exactly the integration defects this suite exists to catch
+  ([[api-integration.<service-stack>]]).
+- **The paging index base is asserted, not assumed**: request page one and assert the value
+  that goes on the wire. A 0-based service read by a 1-based client does not fail — it skips
+  a page — so this assertion is the only thing that catches it.
+- **Redaction is tested**: the same endpoint returning a reduced field set for a lesser role
+  renders the design's "not available to you" affordance, not an error and not a blank.
+- Client regeneration drift fails the build — a suite passing against a stale client is a
+  green build shipping a broken screen.
+
+## Accessibility assertions
+
+Per UX-I every interactive surface asserts: reachable by keyboard, correct accessible name,
+focus placed where the design says on open and on error, and the announced state change
+where the design names one ([[accessibility-implementation]]). An automated scan is a floor,
+not a pass — it cannot see focus order or a meaningless accessible name.
+
+## Discipline
+
+- Tests are **deterministic**: no real network, no wall-clock dependence, no ordering
+  between files, no shared mutable fixture.
+- Time and randomness are injected so a date-dependent screen is testable at any date.
+- Each test names its spec id. A test with no id tests something the design did not ask for
+  — either the design is missing a row, or the test is.
+- No test asserts on a classified value it should not have; fixtures use synthetic data
+  ([[client-security]]).
+
+## Gates
+
+Type-check, lint, accessibility scan, unit and integration tests, and the performance budget
+are all blocking. **A lane that fails any of them fails the build** — there is no
+frontend-only exemption, and a lane that was never compiled reporting green is the exact
+failure the lane model exists to prevent.
+
+## Related
+
+- [[api-client]] — the layer stubs attach to
+- [[api-integration.<service-stack>]] — the real shapes stubs must mirror
+- [[error-handling]] — the states under test
+- [[accessibility-implementation]] — what the accessibility assertion checks

package/assets/guardrails/technology/nextjs/i18n.md

@@ -0,0 +1,57 @@
+# Internationalization Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). Commands: `/aw-spec-design-ui`, `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-X (internationalization is structural).
+
+Internationalization is structural: it is cheap while the surface is being designed and
+expensive once strings are scattered through components. It is applied whether or not a
+second locale ships today.
+
+## Strings
+
+- **Every user-visible string comes from the locale catalogue.** A literal in a component is
+  a string no translator will ever see and no reviewer will ever read as copy.
+- Keys are semantic and scoped to the feature: `order.cancel.confirmTitle`, not `title2`.
+- **Sentences are never concatenated from fragments.** Word order differs by language, so a
+  sentence assembled from parts is untranslatable. Use one message with named placeholders.
+- Plurals and gendered forms use the catalogue's plural rules, not an `if count === 1`.
+- The catalogue carries the CONTEXT a translator needs — where the string appears, what the
+  placeholders are. A bare key with no context produces a confident mistranslation.
+- A missing key is visible in development and falls back deterministically in production; it
+  never renders the raw key to a user, and never renders empty.
+
+## Formatting
+
+- Dates, times, numbers, currencies, units, percentages and relative times are formatted at
+  the boundary, locale-aware. **No hand-rolled format strings.**
+- Timezone is explicit. A timestamp is stored and transported in the contract's canonical
+  form and rendered in the user's zone — never rendered in the browser's zone by accident
+  and never sent in it ([[forms-and-validation]]).
+- Sorting and comparison of user-visible text is locale-aware; a byte-order sort is wrong in
+  most languages.
+- Input parsing is the mirror of output formatting: a decimal comma, a local date order and
+  a grouped number all parse correctly.
+
+## Layout consequences
+
+- Text expands — plan for roughly a third more than English. **A layout that only fits its
+  English copy is a defect**, and it is found at design time from the design's own longest
+  string, not at translation time.
+- Where the design's Experience Scope names a right-to-left locale, direction is a token-
+  level and layout-level concern, not a per-component flip. Logical properties (start/end)
+  are used rather than physical ones (left/right).
+- The document's language is declared, and it changes with the active locale so assistive
+  technology pronounces correctly ([[accessibility-implementation]]).
+
+## Locale selection
+
+- The active locale is resolved once, from the design's stated source — the route, the user's
+  profile, or the request — and every consumer reads that one answer.
+- Locale is a preference, not classified data ([[client-security]]).
+- Switching locale does not lose in-progress work.
+
+## Related
+
+- [[design-system]] — where the strings are rendered
+- [[forms-and-validation]] — locale-aware parsing on the way in
+- [[accessibility-implementation]] — language declaration and announcement

package/assets/guardrails/technology/nextjs/observability.md

@@ -0,0 +1,67 @@
+# Frontend Observability Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE where marked.
+> Commands: `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-VIII (client state carries no secret).
+
+The service is instrumented end to end — OpenTelemetry, structured logs, trace propagation
+across its whole pipeline. This lane's job is to make a user action **findable** in that
+telemetry, and to add nothing to it that must not be there.
+
+## Correlation (NON-NEGOTIABLE)
+
+- Every request from `lib/api/` carries the trace context, so a screen's action can be
+  followed into the service's traces. One HTTP layer is what makes those headers consistent
+  — the other reason raw `fetch` elsewhere is forbidden ([[api-client]]).
+- A correlation id surfaced to the user on an error screen is a support affordance the
+  design specifies, and it is an id — never a stack trace, never a service message
+  ([[error-handling]]).
+- A user-initiated flow that spans several calls carries one correlation across them, so the
+  flow is one story in the telemetry rather than three unrelated requests.
+
+## What is recorded
+
+- Client errors — unhandled exceptions, failed mutations, contract-mapping failures — are
+  reported with the route, the correlation id and the error code.
+- The performance vitals the budget gates on are reported per route
+  ([[performance-budgets]]).
+- Product events, where the design names them, are recorded against a stable event name and
+  a documented property set.
+
+## What is NEVER recorded (NON-NEGOTIABLE)
+
+Mirroring the service's own rule, and extending it to everything the client can see:
+
+- Authentication tokens, credentials, private keys or full payment-card data — in logs,
+  error reports, metric labels, span attributes, breadcrumbs or session replay.
+- Any field the spec's `DC-` ids classify as restricted.
+- **Full request or response bodies.** A body captured "for debugging" carries whatever the
+  service returned, including the fields its projections redacted for other users.
+- URLs with classified data in them — which is the second reason such data never reaches a
+  URL ([[client-security]]).
+
+Where a report needs shape rather than content, record the shape: field names, counts,
+lengths, error codes. Never the values.
+
+## Structured, not ad hoc
+
+- Reporting goes through one configured layer, like requests do. `console.log` is a
+  development tool and is a Forbidden Pattern in production code — it is unstructured,
+  unsampled, unredacted, and visible to the user.
+- Events carry a stable name and typed properties. A message assembled by string
+  interpolation cannot be queried.
+- Sampling and volume are configured, not accidental. Telemetry that costs more than it
+  explains gets turned off, and then nothing is observable.
+
+## Session replay and analytics
+
+- Any replay or analytics tool is a dependency decision recorded in the delta
+  ([[client-security]]) and is configured to mask classified fields **by default**, with
+  masking opt-out per field rather than opt-in.
+- A third-party script never receives a token, a classified field or a URL carrying one.
+
+## Related
+
+- [[api-client]] — where the trace headers are attached
+- [[client-security]] — the storage and disclosure rules this extends
+- [[error-handling]] — what the user sees when something is being reported

package/assets/guardrails/technology/nextjs/performance-budgets.md

@@ -0,0 +1,66 @@
+# Performance Budget Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE.
+> Commands: `/aw-spec-design-ui`, `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-IX (the performance budget is a gate).
+
+A budget that is not enforced is an aspiration. Core Web Vitals thresholds and a per-route
+JavaScript budget are **CI gates**: a route over its budget does not ship.
+
+## What the design owns
+
+`design.ui.md §6` carries the performance row, citing the `SC-` it serves:
+
+- The **target** for this feature's primary flow, taken from the spec's success criteria —
+  not a generic "should be fast".
+- The **structural choice** that meets it: what renders on the server, what is deferred,
+  what is paginated, what is streamed. Performance is a design decision; it cannot be
+  retrofitted by minifying harder.
+- The **device and network floor** from the Experience Scope. A target met on a developer
+  laptop on office wifi is not a target.
+
+## Rendering
+
+- Server-render by default (UX-III). Interactivity is opted into at the leaf, so the
+  client bundle carries only what genuinely needs to run in the browser.
+- Data the first paint needs is fetched on the server. A client fetch-on-mount for
+  above-the-fold content costs a round trip **and** a loading flash the design has to specify.
+- Below-the-fold and interaction-triggered work is deferred — but a deferred boundary is a
+  loading state, and it appears in `§4` like any other.
+- Streaming boundaries are placed where the design says the user can start reading, not
+  wherever the code happened to split.
+
+## Payload
+
+- **A dependency is a design decision recorded in the delta, not an import** (UX-IX). It is
+  judged on what it adds to the route that carries it.
+- Images are sized, modern-format and lazy below the fold; an image with no intrinsic
+  dimensions causes layout shift, which is a scored vital.
+- Fonts are subset, preloaded where they block first paint, and have a fallback that does
+  not shift the layout.
+- No large dependency is pulled in for a small utility, and no dependency is loaded from a
+  CDN at runtime ([[client-security]]).
+
+## Data access
+
+- Lists are paged server-side ([[api-integration.<service-stack>]]). Fetching everything and
+  paging in the browser scales with the data rather than the screen.
+- **The N+1 rule applies to the client too**: a list that fires one request per row is a
+  design defect. The contract offers a batched shape, or the delta asks for one.
+- Requests are deduplicated and superseded requests cancelled ([[api-client]]).
+- Caching and revalidation are declared per fetch (UX-VI) — the cheapest request is the one
+  not made, and the most expensive bug is the stale one.
+
+## The gate
+
+- Core Web Vitals thresholds and the per-route JavaScript budget run in CI and **block**.
+- A budget rise is a reviewed change with a stated reason, not a threshold quietly edited to
+  make the build pass.
+- The budget is measured at the Experience Scope's floor, not at the best case.
+
+## Related
+
+- [[state-management]] — caching, invalidation and what is fetched twice
+- [[api-integration.<service-stack>]] — server-side paging and batching
+- [[error-handling]] — the loading states deferral creates
+- [[design-system]] — layout stability and the token-level image/font decisions

package/assets/guardrails/technology/nextjs/routing-navigation.md

@@ -0,0 +1,52 @@
+# Routing & Navigation Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). Commands: `/aw-spec-design-ui`.
+> Detail layer under `constitution.ui.md` UX-III (server components) and UX-V (every
+> interaction state specified).
+
+The rules `design.ui.md §1 Navigation & Screen Structure` is authored against. The design
+states the navigation SHAPE conceptually — a path pattern, a nesting, a set of siblings —
+and never names a router.
+
+## One screen, one decision
+
+- A screen exists because the user makes a decision there. A screen that only displays is
+  a component on another screen, not a route.
+- A screen belongs to the feature that owns that decision. A screen reading another
+  aggregate's data declares the dependency; it is never duplicated into two features.
+- Every screen row names the `US-` it serves. A user story with no screen home is a
+  coverage failure caught in `§7`, not a gap discovered at `implement-ui`.
+
+## Route shape
+
+- Routes are hierarchical and readable: a nested route means a nested decision, not a
+  shared layout. Shared chrome is a layout concern, not a route.
+- A route parameter identifies a resource; it never carries state, a filter set, or
+  anything the `DC-` ids restrict. Shareable view state belongs in the query string, and
+  the design says which state is shareable.
+- The design names the ENTRY POINT of the feature's primary flow and what a direct,
+  bookmarked hit on each screen must do.
+
+## Access conditions
+
+Every screen states its access conditions and the spec id that imposes them —
+authentication state, role, or record state. Two rules follow, and both are design-level:
+
+- Hidden, disabled and forbidden are three different outcomes. The design says which one
+  each condition produces; `implement-ui` does not get to choose.
+- A client-side access condition is a NAVIGATION affordance, never an enforcement. The
+  service decides; per `CN-`, a route reachable by typing its address must fail server-side.
+
+## Navigation states
+
+Per UX-V a route's own states are specified, not discovered: what shows while the screen's
+data loads, what shows when the resource does not exist, and what shows when the user may
+not see it. Each is an EARS unwanted-behaviour `FR-` in the spec and a `§4` row here.
+
+## Related
+
+- [[component-architecture]] — what a screen composes
+- [[auth-session]] — hidden vs disabled vs denied, and what an unauthenticated deep link does
+- [[error-handling]] — the not-found, denied and failed states a route can reach
+- [[state-management]] — what survives a navigation and what does not
+- [[performance-budgets]] — what a route may cost

package/assets/guardrails/technology/nextjs/state-management.md

@@ -0,0 +1,70 @@
+# Client State Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). Commands: `/aw-spec-design-ui`.
+> Detail layer under `constitution.ui.md` UX-VI (caching declared), UX-VII (one mutation
+> path) and UX-VIII (client state carries no secret).
+
+The rules `design.ui.md §2 Client State` is authored against. State is a DESIGN decision:
+a stale-data defect and a secret in local storage are both design defects, and both are
+invisible by the time they are code.
+
+## Three kinds, three owners
+
+Every entry in `§2` declares which kind it is, and the kind decides the owner:
+
+- **Server-derived** — a projection of what the service holds. Owned by the data-fetching
+  layer's cache, never copied into a store. It has an invalidation trigger; a row without
+  one is incomplete.
+- **Local UI** — open/closed, selected tab, draft input, in-flight flag. Owned by the
+  narrowest component that needs it. It never outlives the screen.
+- **Session** — genuinely client-side, cross-screen, non-secret: locale, theme, a
+  multi-step flow's progress. This is the only kind a global store may hold.
+
+Server-derived state placed in a global store is a design error, not a style preference:
+it forks the cache, and the fork is what serves stale data.
+
+## Invalidation is part of the design
+
+- Every server-derived row names what invalidates it — the mutation, the navigation, or
+  the elapsed time. "Refetch on mount" is not an invalidation policy.
+- Per UX-VI a caching and revalidation policy is DECLARED, never inherited from a
+  default that happens to work.
+- A mutation states what it invalidates in `§5`, and an optimistic update states its
+  rollback. Optimism without a stated rollback is not a design.
+
+## The concurrency token is state
+
+A record read from a concurrency-tracked service arrives with a **version token** — an ETag
+header, a version field on the DTO, or both, depending on the declared service stack
+([[api-integration.<service-stack>]] names which). **That token is part of the record's
+client state and is held beside it**, not discarded on mapping.
+
+- A record held without its token cannot be updated safely: the write either omits
+  `If-Match` and overwrites someone else's change, or it fails.
+- The token is refreshed from every response that returns one. A stale token in state
+  produces a `409` the user cannot resolve by retrying.
+- The token is not user-visible and never reaches the URL.
+
+## Derived, not duplicated
+
+A value computable from state already held is DERIVED and recorded as such. Two rows
+holding the same fact will disagree, and the design is where that is prevented.
+
+## What must never be held
+
+Per UX-VIII, `§2`'s "what must NOT be held" list is mandatory and cites its spec ids:
+
+- Any field the spec's `DC-` ids classify as restricted — including in logs, telemetry,
+  URLs, query strings and browser storage.
+- Credentials, tokens and anything that would let the client answer a question the
+  service must answer.
+- The RESULT of an authorization decision used as if it were the decision. Per `CN-`, the
+  client may hide or disable; the service enforces.
+
+## Related
+
+- [[api-integration.<service-stack>]] — the paging shape, the concurrency token, the caching contract
+- [[component-architecture]] — who reads the state
+- [[api-client]] — where server-derived state comes from
+- [[auth-session]] — what must be cleared on sign-out
+- [[error-handling]] — the states a fetch or mutation passes through

package/assets/guardrails/technology/nextjs/ui-constitution.md

@@ -0,0 +1,166 @@
+# UI Constitution — nextjs (frontend lane)
+
+> The frontend lane's governance base for this stack corpus. It heads the set mapped under
+> `## /aw-spec-ui-constitution` in a project's `tech-rule-bindings.md` — this file, then the
+> project team's `ui-requirements.md` — which `/appweaver constitution` ratifies into
+> `.appweaver/memory/constitution.ui.md`.
+
+Mapping this heading is also what **declares that the project has a frontend lane**. With no
+heading the constitution command skips the UI half and creates no file — so a backend-only
+project without a frontend lane simply leaves this file unmapped.
+
+This base is **domain-free**, exactly like the service lane's `technology-constitution.md`: it is loaded
+before the domain is selected. Domain reaches the UI lane the same way it reaches the service
+lane — through the spec, as `CN-` / `DC-` / `IC-` ids. No regulatory or terminology rule
+belongs here; those live in `domain-constitution.md`.
+
+Principles are a **UX-\*** series. They run parallel to the technology base's I–XV and do not
+continue them — the two govern different lanes and version independently.
+
+## Declared Lane
+
+Stack **nextjs** — Next.js (TypeScript, App Router), lane id `web`, owning `web/`.
+
+Where `.appweaver/stacks.json` declares a frontend lane, that declaration is authoritative for the
+lane id and root; a scaffold that disagrees fails `STACK-MISMATCH:` rather than rewriting it.
+
+## Experience Principles
+
+### UX-I — Accessibility Floor (NON-NEGOTIABLE)
+Every interactive surface meets WCAG 2.2 AA: keyboard reachability, visible focus, correct focus
+order and accessible names are acceptance criteria, not polish. The conformance target arrives as
+a `UX-` standard in the spec's Experience Standards; this principle makes it non-negotiable rather
+than restating it.
+
+### UX-II — The Design System is the Only Source of Visual Truth (NON-NEGOTIABLE)
+Components, spacing, type scale and colour come from the declared design system and its tokens.
+No ad-hoc styling, no second component library, no inline design values.
+
+### UX-III — Server Components by Default
+A route renders on the server unless it needs interactivity or browser-only APIs. `"use client"`
+is an opt-in that a reviewer can justify from the component's own behaviour, never the default,
+and it never appears at a layout root to cover a subtree.
+
+### UX-IV — The Contract is the Only Server Input (NON-NEGOTIABLE)
+The lane consumes the feature's design contract through a generated API client and nothing else
+from the service lane. It never reads the service design, never assumes a table, a handler or a
+route shape, and an interface it needs but the contract lacks is a contract change — not a local
+workaround.
+
+### UX-V — Every Interaction State is Specified
+Loading, empty, error, partial and offline states are EARS unwanted-behaviour `FR-` requirements
+in the spec and are realised in the router's own state files (`loading`, `error`, `not-found`).
+A state the UI can reach and the spec does not describe is a spec defect routed to specify, never
+invented in the component.
+
+### UX-VI — Caching and Revalidation are Declared, Never Inherited
+Every fetch and route segment states its caching and revalidation policy explicitly. A default
+that happens to work is not a policy, and serving stale content the contract marks authoritative
+is a correctness bug, not a performance trade-off.
+
+### UX-VII — Mutations Flow Through One Path
+Writes go through Server Actions or the generated API client, always revalidate what they
+invalidate, and never fire from an ad-hoc `fetch` in a component. Optimistic updates declare
+their rollback.
+
+### UX-VIII — Client State Carries No Secret
+No credential, token or field the contract marks sensitive enters client state, local storage,
+the URL, or telemetry. What the server can decide, the server decides; the client is not a place
+to enforce an authorization rule.
+
+### UX-IX — Performance Budget is a Gate
+Core Web Vitals thresholds and a per-route JavaScript budget are CI gates. A route that exceeds
+its budget does not ship, and a heavy dependency is a design decision recorded in the delta, not
+an import.
+
+### UX-X — Internationalization is Structural
+User-visible strings come from the locale catalogue; formatting of dates, numbers and units is
+locale-aware at the boundary. No concatenated sentences, and no locale assumption baked into a
+component.
+
+### UX-XI — Frontend Test-First
+Every route, form and interaction state ships with tests: component behaviour, contract-client
+integration against the generated types, and an accessibility assertion per interactive surface.
+Snapshot-only tests do not count as coverage.
+
+## Where Each Principle Is Detailed
+
+This file is the thin authority; the enforceable rules live in the corpus beside it. Each
+principle points at the file that details it and the lane command that loads it — so a
+principle can be traced to the phase that applies it, and a rule file can be traced back to
+the principle that ratifies it.
+
+| Principle | Detailed in | Loaded by |
+|---|---|---|
+| UX-I Accessibility Floor | [[accessibility-implementation]] | design-ui · implement-ui |
+| UX-II Design System | [[design-system]] · [[component-conventions]] | design-ui · implement-ui |
+| UX-III Server Components by Default | [[component-architecture]] · [[performance-budgets]] | design-ui · implement-ui |
+| UX-IV The Contract is the Only Server Input | [[api-integration.dotnet-webapi]] / [[api-integration.java-spring]] · [[api-client]] | design-ui · implement-ui |
+| UX-V Every Interaction State is Specified | [[error-handling]] · [[routing-navigation]] · [[forms-and-validation]] | design-ui · implement-ui |
+| UX-VI Caching and Revalidation are Declared | [[state-management]] · [[api-integration.<service-stack>]] | design-ui · implement-ui |
+| UX-VII Mutations Flow Through One Path | [[api-client]] · [[forms-and-validation]] | implement-ui |
+| UX-VIII Client State Carries No Secret | [[client-security]] · [[auth-session]] · [[state-management]] | design-ui · implement-ui |
+| UX-IX Performance Budget is a Gate | [[performance-budgets]] | design-ui · implement-ui |
+| UX-X Internationalization is Structural | [[i18n]] | design-ui · implement-ui |
+| UX-XI Frontend Test-First | [[frontend-testing]] · [[observability]] | implement-ui |
+
+The cross-lane pairing file is **named for the service stack** it pairs with —
+`api-integration.dotnet-webapi.md`, `api-integration.java-spring.md` — and is mapped through
+the `{{backend_stack}}` placeholder, so exactly one of them loads: the one matching the
+backend lane `.appweaver/stacks.json` declares. A repo with no backend lane loads none, and a
+backend stack with no pairing file authored yet is REPORTED rather than silently paired with
+another stack's assumptions. Elsewhere in this corpus the file is referenced as
+`api-integration.<service-stack>` for that reason.
+
+## Mandatory Frontend Folder Structure
+
+The whole layout sits under the lane's root (`web/`) and never adds to the service lane's
+structure.
+
+```
+web/
+  app/                  # App Router — route segments, layouts, loading/error/not-found
+  components/           # design-system compositions, presentational only
+  features/<Feature>/   # one folder per spec feature: its components, hooks, actions
+  lib/api/              # the GENERATED contract client + typed wrappers (never hand-edited)
+  lib/                  # cross-feature client utilities
+  locales/              # locale catalogues
+  tests/                # component, integration and accessibility tests
+```
+
+Generated contract clients land in `lib/api/` and are regenerated, never patched. A feature
+folder mirrors the spec feature name so a slice is traceable in both lanes.
+
+## Conventions, Forbidden Patterns & Quality Gates
+
+- **Naming**: components `PascalCase`, hooks `useX`, route segments kebab-case, one exported
+  component per file.
+- **State**: server state belongs to the data layer's cache, not to a global store; a global
+  store holds only genuinely client-side session state.
+- **Forbidden**: raw `fetch` outside `lib/api/`; business rules in components; `any` on a
+  contract type; hand-edited generated code; `dangerouslySetInnerHTML` without a sanitizer;
+  disabling the accessibility linter inline.
+- **CI gates**: type-check, lint, accessibility scan, unit + integration tests, and the
+  performance budget. All are blocking; a lane that fails any of them fails the build.
+
+## Governance
+
+This half versions independently of `technology-constitution.md` and
+`domain-constitution.md` — a design-system upgrade bumps this file alone. The base amendment
+procedure and SemVer policy apply unchanged; the overrides are:
+
+- Changing the design system, the accessibility conformance target, or the performance budget
+  requires the design authority named for the project in addition to the Principal Engineer.
+- An accessibility waiver is time-boxed, recorded against the `UX-` id it relaxes, and expires.
+- Retiring the frontend lane is a decision to retire this file: unmapping the heading stops the
+  half being re-authored, and removing `.appweaver/memory/constitution.ui.md` is a deliberate,
+  separate act.
+
+## Ratification Metadata
+
+> Carried into `constitution.ui.md` at ratification; the constitution command owns the version
+> bump from there.
+
+- **Version:** 1.0.0
+- **Ratified:** `<YYYY-MM-DD>`
+- **Last Amended:** `<YYYY-MM-DD>`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aw-spec-cli",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "AppWeaver Spec-Driven Development CLI - scaffolds projects with vertical slices, DDD, CQRS, and agent skills",
   "type": "module",
   "main": "dist/index.js",