aw-spec-cli 0.1.7 → 0.1.9

package/assets/.appweaver/orchestrator/rev-templates/ui-design-template.skeleton.md

@@ -0,0 +1,294 @@
+<!--
+  ═══════════════════════════════════════════════════════════════════════════
+  rev-templates/ui-design-template.skeleton.md — SHAPE-ONLY reference.
+
+  This file is the FORMAT reference for the reverse-engineered UI DESIGN
+  TEMPLATE that onboard installs at
+  .appweaver/templates/overrides/ui-design-template.md — the FRONTEND LANE's twin
+  of design-template.skeleton.md, and written only where the CODE has a lane.
+  It carries the section skeleton, the traceability spine, the two deferral
+  ledgers and the authoring contract, and NOTHING ELSE.
+
+  IT NAMES NO FRAMEWORK, ROUTER, STATE LIBRARY, COMPONENT LIBRARY, DESIGN
+  SYSTEM OR STYLING APPROACH. "Component", "screen", "route" and "state
+  container" are CONCEPTUAL here — the same way the service design says
+  "repository" without naming an ORM. The framework binds later, at
+  ⌛ `ui-implement`, from constitution.ui.md plus that command's rule set. A
+  named example in a skeleton becomes law in a lane it does not fit, and the
+  frontend is where that risk is highest. Every [BRACKET] is filled FROM THE
+  LANE'S OWN CODE.
+
+  THIS IS A TEMPLATE OF A TEMPLATE. What onboard generates from it is the
+  project's UI design TEMPLATE — [PLACEHOLDER] tokens and authoring comments
+  intact — which ⌛ `ui-design` then fills once per feature into
+  specs/<Feature>/design.ui.md. Onboard replaces the STRUCTURE, not the content.
+
+  THE SECTION LIST IS RATIFIED, NOT INVENTED. §1–§9 below are the sections
+  aw-spec specifies for design.ui.md (Navigation & screen structure · Client
+  state · Component structure · Interaction & flow · Contract binding ·
+  Cross-cutting · Traceability · DA-n · WA-n), keeping the neutral bones the
+  service design earned. What the CODE supplies is what goes IN them — the
+  lane's real screens, its own composition axes, its state and styling
+  conventions — never which sections exist.
+
+  TWO SECTIONS ARE MANDATORY EVEN WHEN THIN. §4 Interaction & Flow and §6
+  Cross-Cutting are the two a backend-shaped process silently drops, and they
+  are where most UI defects live: loading, empty, error and permission-denied
+  states, focus and keyboard behaviour, and what must never reach the client.
+  A lane whose code shows little of either records THAT, as-built — an app with
+  no error states gets a section saying so, not a section quietly omitted.
+
+  §5 IS THE LANE BOUNDARY. Contract binding is the only place the service lane
+  enters: the UI design reads the WHOLE spec but only a PROJECTION of the
+  service design (⌛ specs/<Feature>/design-contract.md). The requirement is
+  shared and must not fork; the implementation is not shared and must not leak.
+
+  DISCIPLINE THIS SKELETON ENFORCES (structurally — there is no project content
+  here to leak):
+    • AS-BUILT — every structural statement is confirmed by reading UI source.
+      State a partial or inconsistent convention at the level the code reaches,
+      and name the dominant form rather than picking a winner the code has not.
+    • ONE AXIS PER RECURRING STRUCTURE — §3's subsections are the lane's OWN
+      organisation (whatever it groups by), not a taxonomy imposed on it.
+    • NOT DEBT — a lane organised unlike a reference frontend is the as-built
+      shape (§0), not a §9 deviation.
+    • ONE LANE — this document governs the frontend lane only. It carries no
+      service-lane structure and no domain rule; the domain reaches it as spec
+      ids, exactly as it reaches the service design.
+  ═══════════════════════════════════════════════════════════════════════════
+-->
+# UI Design: [AGGREGATE]
+
+**Aggregate (feature)**: `[Aggregate]`
+
+**Design home**: `specs/[Aggregate]/design.ui.md`
+
+**Source spec**: `specs/[Aggregate]/spec.md`
+
+**Contract**: `specs/[Aggregate]/design-contract.md`
+
+**Version**: v1.0
+
+**Status**: Draft
+
+<!--
+  WHAT THIS DOCUMENT IS
+  =====================
+  The single, living high-level UI design for ONE feature's experience — the
+  MEDIATOR between spec.md (WHAT/WHY) and the frontend code ⌛ `ui-implement`
+  generates. It carries screens, navigation, state, composition, interaction
+  and the service binding; it is not code and it is not a visual comp.
+
+  ANCHORING RULES
+  - Every element traces UP to a spec id (FR-/BR-/CN-/DC-/IC-/US-/SC-) and the
+    experience obligations of the spec are covered DOWN here (§7). No screen
+    without a spec reason; no user story without a screen home.
+  - THE SPEC IS THE ONLY DOMAIN INPUT — the same rule the service design keeps.
+    This document reads the spec + the lane's own standards, never the domain
+    rule files.
+  - THE CONTRACT IS THE ONLY SERVICE INPUT (§5). Read the design contract, never
+    the service design.
+
+  STRUCTURE FOLLOWS THIS LANE'S CODE
+  - [GENERATED_LANE_STRUCTURE_NOTE] — form: one or two sentences naming the
+    composition convention this lane actually follows and where its screens,
+    shared components, state and styles live, with the paths that evidence it.
+
+  TECHNOLOGY-AGNOSTIC (mandatory)
+  - Name no framework, router, state library or component library. Describe a
+    component by its RESPONSIBILITY, its INPUTS (props/params as field shapes),
+    the EVENTS it raises and the STATES it can be in. The same design must be
+    realisable on another frontend stack without edits.
+
+  HOW TO AUTHOR
+  - Fill every [PLACEHOLDER]; keep the section order. §4 and §6 are never
+    omitted. §8 and §9 are MANDATORY ledgers — empty reads "None (as of vX.Y)".
+  - GROUND each filled section in the ACTUAL UI CODE and the reverse-engineered
+    lane governance — cite real component/route/store/stylesheet paths and the
+    constitution.ui.md UX principle the decision rests on.
+  - Delete these authoring comments as you fill each section.
+-->
+
+## 0. Design Overview
+
+<!-- One paragraph: the shape of this feature's experience and the 3–5 decisions
+     that matter most (the entry point, the primary flow, the hardest trade-off).
+     The lane's standing conventions are recorded below, not restated per
+     screen. -->
+
+[The essence of this feature's experience in 3–6 sentences.]
+
+### As-Built Lane Structure
+
+[AS_BUILT_LANE_STRUCTURE_CONTENT]
+<!-- Form: the convention THIS lane follows — its root, how screens/views are
+     organised and named, where shared components live, how state and
+     server data are held, how styling is applied, and the lane's build/test
+     tooling — each with a representative code path. A new feature's UI ALIGNS
+     to this rather than introducing a second convention. Where the UI is
+     rendered inside the service tree and owns no root, say so. -->
+
+### Ubiquitous Language (design delta)
+
+<!-- Only the terms this design introduces or sharpens beyond the spec — a
+     screen name, a state name, a shared component concept. These become code
+     identifiers. -->
+
+| Term | Meaning in this design |
+|---|---|
+| [Screen / component / state name] | [precise definition] |
+
+## 1. Navigation & Screen Structure
+
+<!-- The screen inventory and how a user moves between them. One row per screen
+     this feature owns. A screen belongs to the feature that owns the DECISION
+     the user makes there; a screen that reads from another aggregate declares a
+     Depends-On edge rather than being duplicated. -->
+
+| Screen | Purpose | Entered from | Leads to | Serves |
+|---|---|---|---|---|
+| `[Screen]` | [the decision made here] | [entry point] | [next screens] | US-[n] · FR-[nnn] |
+
+**Route / navigation shape**: [how screens are addressed and nested in this
+lane, stated conceptually — a path pattern, a stack, a tab set — read from the
+code, not named after a router.]
+
+**Access conditions**: [which screens require what — authentication state, a
+role, a record state — each citing the spec id that imposes it, or `None`.]
+
+## 2. Client State
+
+<!-- What the client holds, where it lives, and who may write it. Distinguish
+     server-derived data from local UI state. Include invalidation/refresh
+     triggers — a stale-data defect is a design defect, not an implementation
+     one. -->
+
+| State | Kind | Owner / scope | Shape | Written by | Invalidated by |
+|---|---|---|---|---|---|
+| `[State]` | [server-derived / local UI / session] | [scope] | [field: type, …] | [screen/component] | [event] |
+
+## 3. Component Structure
+
+<!-- ONE `### 3.n` SUBSECTION PER RECURRING COMPOSITION AXIS THIS LANE USES,
+     each TITLED with the lane's OWN name for it. The count and titles are the
+     code's answer — the slots below are illustrative positions, not a required
+     set. In each: the components that live there, what they are responsible
+     for, their inputs as field shapes, and the events they raise. -->
+
+### 3.1 [LANE_COMPOSITION_AXIS_NAME]
+
+<!-- [What this axis holds in this lane + the representative path that evidences
+     it.] -->
+
+| Component | Responsibility | Inputs (field shape) | Events raised | Serves |
+|---|---|---|---|---|
+| `[Component]` | [what it is responsible for] | [field: type, …] | `[event]` | FR-00X · US-Y |
+
+### 3.n [LANE_COMPOSITION_AXIS_NAME]
+
+<!-- … one per axis the lane's code actually shows, then stop … -->
+
+## 4. Interaction & Flow
+
+<!-- MANDATORY — never omitted, never thinned to a happy path. For each
+     significant interaction: the states it passes through and what the user
+     sees in each. Cover loading, empty, error, permission-denied and
+     in-flight/disabled states, plus validation timing and what happens on
+     cancel or navigate-away. Where the lane's code shows a state it does NOT
+     handle, record that as-built here — it is a real finding, not a gap to
+     paper over. -->
+
+| Interaction | States | What the user sees | Serves |
+|---|---|---|---|
+| `[interaction]` | [idle → in-flight → success / error / empty] | [per-state behaviour] | US-[n] · FR-[nnn] |
+
+**Validation & feedback**: [when validation runs and how failures are surfaced,
+citing the BR-/FR- ids being enforced client-side. A client-side check NEVER
+replaces the service-side rule — it restates it for feedback.]
+
+**Keyboard, focus & announcement**: [what the lane's code actually does, at the
+level it reaches, citing the UX principle that governs it — or plainly that it
+does none.]
+
+## 5. Contract Binding
+
+<!-- THE LANE BOUNDARY. One row per service operation this feature's UI depends
+     on, taken from ⌛ specs/[Aggregate]/design-contract.md — the projection the
+     service design emits. Read the contract, never the service design. Where no
+     contract document exists yet, bind against the spec's own IC-/FR- surface
+     and record that as a §8 assumption. -->
+
+| Screen / component | Operation (from the contract) | Sends (field shape) | Receives (field shape) | Failure handling | Serves |
+|---|---|---|---|---|---|
+| `[Screen]` | `[operation]` | [field: type, …] | [field: type, …] | [§4 state] | FR-00X · IC-00X |
+
+**Contract deltas needed**: [anything the experience requires that the contract
+does not offer — raised back to the service lane, never worked around in the
+client. Or `None`.]
+
+## 6. Cross-Cutting
+
+<!-- MANDATORY — never omitted. One row per concern this feature's UI must
+     honour, each tracing to a spec id or to a constitution.ui.md UX principle
+     via a §8 DA-n. Keep only the rows this lane's governance actually carries;
+     state a concern the code does not address AS-BUILT rather than dropping the
+     row. -->
+
+| Concern | Design decision | Serves |
+|---|---|---|
+| Data exposure on the client | [what MUST NOT reach the client or its logs/storage] | DC-00X |
+| Authorization surface | [what is hidden vs disabled vs enforced server-side] | CN-00X |
+| Accessibility | [what this lane enforces, at the level it reaches] | [UX-n via DA-n] |
+| Internationalization | [as-built handling, or that there is none] | [spec id / DA-n] |
+| Performance & responsiveness | [target + structural choice] | SC-00X |
+| Error & offline behaviour | [as-built handling] | FR-00X |
+
+## 7. Traceability (the spine)
+
+<!-- The two-way guarantee for the lane: every experience obligation in the spec
+     has a home here, and every UI element has a spec reason. The last column
+     names THIS document's own sections. A US- with no screen is a coverage
+     failure. -->
+
+| Spec id | Type | UI element(s) | Section |
+|---|---|---|---|
+| US-1 | story | [screens + flow realising it] | [§ refs] |
+| FR-001 | requirement | [screen / component / state] | [§] |
+| CN-001 | constraint | [where honoured in the UI] | [§] |
+| DC-001 | classification | [what is withheld from the client] | §6 |
+| IC-001 | contract | [binding row] | §5 |
+| SC-001 | success | [where met + how verified] | [§] |
+
+## 8. Assumptions (to clarify later)
+
+<!-- MANDATORY LEDGER. Every default or open interpretation this design commits
+     to so it can proceed without blocking — including any element
+     constitution.ui.md mandates that has no per-feature spec id (state the
+     basis as "per constitution.ui.md UX-<n>"). Empty → "None (as of vX.Y)". -->
+
+| id | Assumption | Why deferred | Impact if wrong | Owner / resolve-by |
+|---|---|---|---|---|
+| DA-1 | [what was assumed] | [why not clarified now] | [blast radius] | [role / phase] |
+
+## 9. Deviations & Deferred Decisions (to clear later)
+
+<!-- MANDATORY LEDGER. Experience debt KNOWINGLY taken — a screen that does too
+     much, a duplicated component, a state held in the wrong place — with the
+     proper end-state and the trigger that forces the cleanup. AS-BUILT
+     DISCIPLINE: only debt the CODE evidences. A lane organised unlike a
+     reference frontend is the as-built shape (§0), not a deviation.
+     Empty → "None (as of vX.Y)". -->
+
+| id | Deviation taken | Proper end-state | Trigger to revisit | Serves / caused by |
+|---|---|---|---|---|
+| WA-1 | [the shortcut/coupling] | [the clean design] | [what forces it] | [FR / constraint] |
+
+## Change History
+
+<!-- In lockstep with spec.md and design.md — a change that touches both lanes
+     closes on ONE version bump. finalize-delta appends the row; close-delta
+     bumps the version and stamps it into the header. Newest last. -->
+
+| Version | Date | Change | User stories | CR |
+|---------|------|--------|--------------|-----|
+| v1.0 | [DATE] | Initial UI design | US-1 | — |

package/assets/.appweaver/orchestrator/workflows/_smoke.orch.yaml

@@ -0,0 +1,160 @@
+# =============================================================================
+# _smoke — CI smoke workflow for the orchestrator engine (no model, no writes
+# outside .appweaver/orchestrator/.smoke-out)
+#
+# Exercises every extended construct in one run: inputs, set (raw object),
+# execute_script (read-only subcommand), verify_context gates, ask
+# (non-interactive default), foreach + while loops + break, agent_query
+# (mock:), agent_author (mock content), build_context, include
+# (domain-select module), dispatch_hooks (empty).
+#
+# Run:
+#   python3 .appweaver/orchestrator/orchestrator.py \
+#     .appweaver/orchestrator/workflows/_smoke.orch.yaml --non-interactive --json
+# Expected: status ok, echo=hello, sum of foreach passes, smoke.md written.
+# =============================================================================
+
+name: orch-smoke
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional text echoed into the authored artifact.
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+vars:
+  out_dir: .appweaver/orchestrator/.smoke-out
+  seen: ""
+
+workflow:
+
+  # set with a raw list (resolve_value keeps it a real list)
+  - id: seed
+    action: set
+    vars:
+      fruits: ["apple", "banana"]
+      echo: "hello"
+
+  # F1: read-only script subcommand; outputs[] binding
+  - id: script_ro
+    action: execute_script
+    script: { ref: actions }
+    subcommand: list-domains
+    outputs:
+      - { name: domains, from: "$.domains" }
+
+  # F2: gates — value gate + non-empty gate (informational, no stop)
+  - id: gate_value
+    action: verify_context
+    require_value: echo
+    equals: "hello"
+    on_mismatch: stop
+    on_mismatch_message: "set/resolve is broken"
+  - id: gate_nonempty
+    action: verify_context
+    require_non_empty: domains
+    on_empty_message: "no domains found (allowed in smoke)"
+
+  # F7: ask — --non-interactive picks the first option
+  - id: pick_mode
+    action: ask
+    prompt: "Smoke mode?"
+    options: ["fast", "slow"]
+    answer_var: mode
+  - id: gate_mode
+    action: verify_context
+    require_value: mode
+    equals: "fast"
+    on_mismatch: stop
+    on_mismatch_message: "non-interactive ask default is broken"
+
+  # F3: foreach over a list var, binding item + item_index
+  - id: each_fruit
+    action: loop
+    over: "{{fruits}}"
+    as: fruit
+    steps:
+      - id: collect
+        action: set
+        vars:
+          seen: "{{seen}}{{fruit}}@{{fruit_index}};"
+
+  # while + break still work
+  - id: count
+    action: loop
+    while: "true"
+    max_iterations: 3
+    steps:
+      - id: stop_at_1
+        action: break
+        condition: "{{iteration}} == 1"
+
+  # F6: structured query — mock: supplies the result in mock transport
+  - id: q_shape
+    action: agent_query
+    schema: { ok: true, items: [] }
+    mock: { ok: true, items: ["one", "two"] }
+    task: Report ok plus a short list of items.
+    outputs:
+      - { name: q_ok,    from: "$.ok" }
+      - { name: q_items, from: "$.items" }
+  - id: gate_q
+    action: verify_context
+    require_true: q_ok
+    on_false: stop
+    on_false_message: "agent_query mock/result binding is broken"
+
+  # F3 again: foreach over a query-produced list
+  - id: each_item
+    action: loop
+    over: "{{q_items}}"
+    as: it
+    steps:
+      - id: collect_items
+        action: set
+        vars:
+          seen: "{{seen}}{{it}};"
+
+  # context management stays with the orchestrator: envelope for the author step
+  - id: ctx_author
+    action: build_context
+    context:
+      - { path: "{{out_dir}}/smoke.md", optional: true }
+
+  # F5: authored artifact — engine writes the file (mock content here)
+  - id: author_doc
+    action: agent_author
+    output_target: { type: file, path: "{{out_dir}}/smoke.md" }
+    task: "Write a one-paragraph smoke report. Echo: {{echo}} {{USER_INPUT}}"
+
+  # F2: file gate against what the engine just wrote
+  - id: gate_file
+    action: verify_context
+    required_files: ["{{out_dir}}/smoke.md"]
+
+  # F9: include — the shared domain-select module (read-only script + asks;
+  # non-interactive: gate→continue, mode→all)
+  - id: domain
+    action: include
+    module: .appweaver/orchestrator/modules/domain-select.orch.yaml
+    with:
+      command: specify
+
+  # F8: hooks — empty var logs 'none'
+  - id: hooks
+    action: dispatch_hooks
+    hooks_from_variable: no_hooks_declared
+
+outputs:
+  echo: "{{echo}}"
+  mode: "{{mode}}"
+  seen: "{{seen}}"
+  q_items: "{{q_items}}"
+  domain: "{{domain}}"
+  note: "all engine constructs exercised"