aw-spec-cli 0.1.13 → 0.1.15

package/assets/.appweaver/orchestrator/workflows/aw-spec-design-ui.orch.yaml

@@ -1,386 +0,0 @@
-# =============================================================================
-# aw-spec-design-ui (orchestrator) — the FRONTEND LANE's Design phase
-#
-# Authors ONE high-level UI design document per feature — specs/<Aggregate>/design.ui.md
-# — the frontend lane's twin of design.md and the MEDIATOR between the spec and the
-# frontend code. Its sections are the experience, not the four clean-architecture
-# layers: navigation & screen structure · client state · component structure ·
-# interaction & flow · contract binding · cross-cutting · traceability, plus the same
-# two deferral ledgers (DA-n / WA-n). `implement-ui` GENERATES the components from it.
-# See .appweaver/DESIGN-FORMAT.md ("Frontend lane variant") +
-# .appweaver/templates/ui-design-template.md.
-#
-# WHY A SEPARATE COMMAND, NOT A UI BRANCH INSIDE `design`. The two lanes are governed
-# by different constitution halves, take their rules from different map headings, and
-# own disjoint source paths. Keying the rule maps on `## /aw-spec-design-ui` gives the
-# lane its own rule set for zero mechanism change; a UI section inside design.md would
-# put the lane's structure under the service lane's rules and hand this phase the whole
-# service design to read.
-#
-# THE LANE BOUNDARY IS §5. This phase reads the WHOLE spec — the experience is stated
-# there, as UX- standards and as the interaction its user stories imply — but only the
-# service's PUBLISHED SURFACE: the spec's IC- ids and, where design.md exists, the API
-# contracts it states. No table, handler or persistence choice crosses that line.
-# design.md is OPTIONAL context for exactly that reason: a UI-only project authors §5
-# from the spec's IC- surface and records a DA-n. (⌛ B-11 replaces the optional
-# design.md with design-contract.md, the projection `design` will emit — the prompt's
-# rule does not change when it does.)
-#
-# UX- LIVES HERE AND ONLY HERE. design.md deliberately excludes the spec's Experience
-# Standards — the service design realises no experience standard — so a UX- that reaches
-# neither design is a dropped requirement. §7 Traceability is where that is caught.
-#
-# TEMPLATE-DRIVEN AUTHORING (greenfield-safe), the same pair `design` uses:
-#   • GREENFIELD (default) — the experience template shipped at
-#     .appweaver/templates/ui-design-template.md. Sections §0–§9 as above.
-#   • BROWNFIELD — when /appweaver onboard has GENERATED the code-derived
-#     `ui-design-template` override (reverse-engineered from the repo's own UI source;
-#     override_active), a NEW feature added to an existing app is authored with the
-#     as-built composition axes instead, so it slots into the lane already there.
-#
-# BOOTSTRAP ONLY. The trigger is design.ui.md's OWN existence, symmetric with how
-# `design` keys off design.md. No design.ui.md ⇒ author the master. One already there
-# ⇒ the change is a DELTA, and ⌛ `delta-design-ui` owns that record — this command
-# stops rather than overwrite a master finalize-delta is the sole writer of.
-#
-# Forward path:  select-stack → select-domain → constitution → select-feature →
-#                specify → design-ui → ⌛ analyze-design-ui → implement-ui → build
-#
-# Launch:  /appweaver design-ui [guidance]
-# Prereq:  /appweaver specify   (the spec is this phase's only domain input)
-# =============================================================================
-
-name: aw-spec-design-ui
-description: "Author the frontend lane's single high-level design.ui.md from the spec — the experience twin of design.md, and the MEDIATOR between spec.md and the code implement-ui generates. Sections are navigation & screen structure, client state, component structure, interaction & flow, contract binding, cross-cutting, traceability and the two deferral ledgers. Technology-agnostic: no framework, router, state library or component library appears; the stack binds at implement-ui. Realises the spec's UX- Experience Standards, which design.md excludes by contract. The service lane enters only at §5 Contract Binding, as its published surface. Authoring is template-driven — the shipped experience template by default, or the code-derived as-built structure when onboard installed it as the ui-design-template override. Bootstrap only: an existing design.ui.md means the change is a delta and routes to delta-design-ui."
-version: 1.0.0
-agent_agnostic: true
-dialect: aw-spec.orchestrator/v1
-
-inputs:
-  user_input:
-    description: Optional design guidance (flow preferences, screen decomposition hints, constraints).
-    required: false
-    bind: USER_INPUT
-
-scripts:
-  actions:
-    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
-    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
-
-# Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The lane's
-# FRONTEND rule files are CONFIGURATION, loaded per-command from
-# guardrails/projects/<project>/tech-rule-bindings.md under `## /aw-spec-design-ui` by the
-# tech-select module. Per the rule-partition this phase loads NO domain rule file —
-# the domain reaches it as spec ids, exactly as it reaches design.md. The lane's
-# ratified base arrives via constitution.ui.md (referred to directly, as-is — NOT
-# mapped). (missing files skipped at assembly time)
-standards:
-  - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
-
-vars:
-  ui_design_mode: "bootstrap_gf"   # resolved below → bootstrap_gf | bootstrap_bf
-  ui_is_delta: "no"                # "yes" ⇒ design.ui.md already exists ⇒ the change is a delta
-  version: ""
-
-workflow:
-
-  # 0. FRONTEND rule files → sticky standards (configuration, not hardcoded).
-  #    No blocking gate: a project that has not mapped the heading soft-continues,
-  #    because constitution.ui.md still carries the lane's ratified base.
-  - id: tech_select
-    action: include
-    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-design-ui }
-
-  # 1. The lane must EXIST. This phase writes a document, not code, so it asks the
-  #    declaration whether there is a frontend lane at all — not the lane-gate module,
-  #    whose on-disk check would refuse a greenfield project that has declared `web/`
-  #    but not scaffolded it yet. A UI design is authored before the UI exists; that is
-  #    the point of designing.
-  - id: lane_resolve
-    action: execute_script
-    on_error: continue      # never crash raw on an undeclared lane — the gate below explains it
-    script: { ref: actions }
-    subcommand: lane-resolve
-    outputs:
-      - { name: fe_declared,  from: "$.frontend_declared" }
-      - { name: lane_id,      from: "$.frontend_lane_id" }
-      - { name: lane_title,   from: "$.frontend_title" }
-      - { name: lane_language, from: "$.frontend_language" }
-      - { name: lane_ecosystem, from: "$.frontend_ecosystem" }
-      - { name: lane_root,    from: "$.frontend_source_path" }
-
-  - id: require_lane
-    action: verify_context
-    require_true: fe_declared
-    on_false: stop
-    on_false_message: "No frontend lane is declared in .appweaver/stacks.json, so there is no experience to design. Run /appweaver select-stack and declare the UI stack plus its source path, then re-run design-ui. A project that genuinely has no UI designs the service lane alone with /appweaver design."
-
-  # 2. Resolve the current feature and require its spec — this phase's only domain input.
-  - id: feature_paths
-    action: execute_script
-    on_error: continue      # never crash raw on 'no feature set' — the gate below explains it
-    script: { ref: actions }
-    subcommand: feature-paths
-    outputs:
-      - { name: feature_dir,      from: "$.feature_dir" }
-      - { name: spec_file,        from: "$.spec_file" }
-      - { name: spec_exists,      from: "$.spec_exists" }
-      - { name: service_design,   from: "$.design_file" }
-      - { name: ui_design_exists, from: "$.ui_design_exists" }
-
-  - id: require_feature
-    action: verify_context
-    require_non_empty: feature_dir
-    on_empty: stop
-    on_empty_message: "No active feature. Run /appweaver select-feature first (pick or create the aggregate, e.g. Order), then re-run design-ui."
-
-  - id: verify_spec
-    action: verify_context
-    require_true: spec_exists
-    on_false: stop
-    on_false_message: "No spec.md for the current feature. Run /appweaver specify first — the spec is this phase's only domain input, and its Experience Standards (UX-) are what design.ui.md realises."
-
-  # 2a. BOOTSTRAP ONLY. design.ui.md's own existence is the delta trigger, symmetric
-  #     with design's design.md trigger. Stop rather than overwrite the master: it is
-  #     finalize-delta's to write, and ⌛ delta-design-ui owns the change record.
-  #     The flag is carried as a literal string because the two readers disagree on a
-  #     JSON boolean: a `condition:` resolves it through json.dumps ("false"), while
-  #     `require_value` reads the variable raw (str(False) -> "False"). Setting a
-  #     string under a condition keeps both readings the same one.
-  - id: mark_delta
-    condition: "{{ui_design_exists}} == true"
-    action: set
-    vars: { ui_is_delta: "yes" }
-
-  - id: refuse_delta
-    action: verify_context
-    require_value: ui_is_delta
-    equals: "no"
-    on_mismatch: stop
-    on_mismatch_message: "design.ui.md already exists for this feature, so a change to it is a DELTA, not a re-bootstrap — the master is finalize-delta's to write. ⌛ /appweaver delta-design-ui, which owns the delta-design.ui.md record, is not built yet. To regenerate the master from scratch instead, delete specs/<Feature>/design.ui.md first."
-
-  # 3. Read the version so the authored header is stamped consistently with its siblings.
-  - id: read_change
-    action: execute_script
-    on_error: continue
-    script: { ref: actions }
-    subcommand: version-read
-    args: ["--feature-dir", "{{feature_dir}}"]
-    outputs:
-      - { name: version, from: "$.version" }
-
-  # 4. Scaffold design.ui.md from the LANE's template pair (--lane ui resolves
-  #    ui-design-template → design.ui.md, so no caller can write the service template
-  #    under the UI lane's filename). Idempotent; the delta refusal above already
-  #    guarantees it is a create.
-  - id: ui_design_scaffold
-    action: execute_script
-    script: { ref: actions }
-    subcommand: design-scaffold
-    args: ["--feature-dir", "{{feature_dir}}", "--lane", "ui"]
-    outputs:
-      - { name: ui_design_doc,  from: "$.design_doc" }
-      - { name: ui_override,    from: "$.override_active" }   # true ⇒ onboard installed the code-derived template
-
-  # 4a. Resolve the authoring MODE. Ordered override rather than a branch — the engine
-  #     has no compound conditions: state the greenfield default, let the code-derived
-  #     override replace it.
-  - id: mode_brownfield
-    condition: "{{ui_override}} == true"
-    action: set
-    vars: { ui_design_mode: "bootstrap_bf" }
-
-  # 5. Pre-execution hooks.
-  - id: resolve_pre_hooks
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "before_design_ui"]
-    outputs:
-      - { name: before_hooks, from: "$.hooks" }
-  - id: dispatch_pre_hooks
-    action: dispatch_hooks
-    hooks_from_variable: before_hooks
-
-  # ═══════════ GREENFIELD — the shipped experience template (§0–§9) ═══════════
-  # build_context REPLACES the per-request envelope; the sticky frontend standards
-  # stay prepended. The ENGINE writes ui_design_doc.
-  - id: ctx_ui_design
-    condition: "{{ui_design_mode}} == bootstrap_gf"
-    action: build_context
-    context:
-      - { path: "{{ui_design_doc}}" }                                    # the copied template = section structure
-      - { path: "{{spec_file}}" }                                        # the source of truth (UX/US/FR/CN/DC/IC/SC)
-      - { path: .appweaver/DESIGN-FORMAT.md }                            # the design-doc contract + its frontend lane variant
-      - { path: .appweaver/memory/constitution.ui.md, optional: true }   # the lane's ratified UX-* base — optional: a lane may be declared before it is ratified
-      - { path: "{{service_design}}", optional: true }                   # §5 ONLY — the service's published surface, never its internals
-  - id: gen_ui_design
-    condition: "{{ui_design_mode}} == bootstrap_gf"
-    action: agent_author
-    output_target: { type: file, path: "{{ui_design_doc}}" }
-    task: |
-      Author the MASTER UI design (the target design.ui.md in context) for this
-      feature's EXPERIENCE by filling out the template from the feature spec + the
-      loaded frontend standards. This is the frontend lane's MEDIATOR between the spec
-      and the components `implement-ui` will generate. Guidance: {{USER_INPUT}}
-      Rules:
-      - THE SPEC IS THE ONLY DOMAIN INPUT. You have the spec + frontend standards, and
-        NO domain rule files. The domain arrives as spec ids only — realise them, and
-        invent no domain rule the spec omits (an unavoidable new concept → §8 DA-n).
-      - Keep the template's section order and headings: §0 Design Overview, §1
-        Navigation & Screen Structure, §2 Client State, §3 Component Structure, §4
-        Interaction & Flow, §5 Contract Binding, §6 Cross-Cutting, §7 Traceability,
-        §8 Assumptions, §9 Workarounds, Change History.
-      - REALISE THE SPEC'S EXPERIENCE CONTENT:
-        • Experience Standards (UX-) are THIS document's to realise — design.md
-          excludes them by contract, so a UX- with no home here is a DROPPED
-          requirement, not a tidy omission. Every UX- gets a §7 row.
-        • Experience Scope (actors · channels · device/browser/AT floors) bounds §1
-          and §6 — design for the floors the spec names and no more.
-        • Each User Story (US-) gets a screen home in §1 and a flow in §4. A US- with
-          no screen is a coverage failure.
-        • Interaction-state requirements are ordinary FR- ids (the EARS
-          unwanted-behaviour form). Each one gets a §4 row.
-      - REALISE THE LIFTED CONSTRAINTS, each citing its spec id:
-        • CN- → §6 Authorization surface and the §1 access conditions (what is hidden
-          vs disabled vs enforced server-side — the client never becomes the authority).
-        • DC- → §2 "what must NOT be held" and the §6 data-exposure row: what may not
-          reach the client, its logs, its storage or its URLs.
-        • IC-/SC- → §5 binding rows and the §6 performance row respectively.
-      - §4 INTERACTION & FLOW AND §6 CROSS-CUTTING ARE NEVER OMITTED, however thin the
-        feature. Loading, empty, error, permission-denied and in-flight states, plus
-        validation timing, focus placement and keyboard reachability, are where most UI
-        defects live. A state the UI can reach that the spec does not describe is a SPEC
-        gap: log it as a §8 DA-n and say it routes to `specify`; never invent the
-        requirement here.
-      - §5 IS THE LANE BOUNDARY. Bind against the service's PUBLISHED surface only —
-        the spec's IC- ids, and where design.md is in context, the API contracts it
-        states. CITE those contracts; do NOT restate, re-derive or contradict them, and
-        introduce NO server-side behaviour, persistence assumption or handler detail.
-        Anything the experience needs that the surface does not offer is a CONTRACT
-        DELTA raised back to the service lane under "Contract deltas needed" — never a
-        workaround in the client. Where no service design is in context, bind from the
-        spec's IC- surface and record that as a §8 DA-n.
-      - CONSTITUTION-MANDATED CROSS-CUTTING (from the loaded UI constitution, NOT the
-        spec): a NON-NEGOTIABLE UX principle you must apply that has no per-feature spec
-        id. APPLY it, and because it is not spec-derived, LOG it as a §8 DA-n whose
-        basis cites the mandating principle ("per constitution.ui.md UX-<n>"); set the
-        corresponding §6 row's "Serves" to that DA-n. Do NOT fabricate a spec UX- for
-        it, and do NOT leave it uncited.
-      - TECHNOLOGY-AGNOSTIC: name no framework, router, state library, component library
-        or styling approach. Describe a component by its RESPONSIBILITY, its INPUTS as
-        field shapes, the EVENTS it raises and the STATES it can be in; describe routing
-        as a conceptual shape. The framework binds at `implement-ui`. Do NOT include
-        file placement, naming conventions or test mechanics — those are the UI
-        constitution's and `implement-ui`'s, identical for every feature.
-      - The header's Lane field is `{{lane_id}}`. That identifier is the ONLY thing you
-        are told about the lane: its framework and language are deliberately withheld,
-        because a design that knows them starts naming them.
-      - STAY IN THE LANE'S SCOPE. This feature's screens only. The app shell, global
-        layout and the design system belong to no single feature: cite them under
-        "Screens this feature does NOT own" / "Reused from the design system", and do
-        not claim or redesign them here.
-      - §7 TRACEABILITY IS THE SPINE — fill it completely, both ways: a row for EVERY
-        UX-, US-, and for every CN-/DC-/IC-/SC- with an experience obligation, so no
-        lifted constraint is silently dropped; and no UI element without a spec reason.
-      - Fill the two ledgers: §8 Assumptions (DA-n, to clarify later) and §9 Workarounds
-        (WA-n, to clear later). Empty → "None (as of v1.0)".
-      - This is v1.0: set the initial Change History row. No component code anywhere.
-
-  # ═══ BROWNFIELD — code-derived template, NEW feature in an EXISTING app ════
-  # Same contract as above (technology-agnostic, spec is the only domain input, full §7
-  # and both ledgers), with ONE difference: the STRUCTURE follows the code-derived
-  # template's own composition axes and the lane's as-built conventions, so a new
-  # feature slots into the app already there instead of introducing a second convention.
-  # Runs only when onboard generated the ui-design-template override.
-  - id: ctx_ui_design_brownfield
-    condition: "{{ui_design_mode}} == bootstrap_bf"
-    action: build_context
-    context:
-      - { path: "{{ui_design_doc}}" }                                    # the scaffolded CODE-DERIVED template = as-built section structure
-      - { path: "{{spec_file}}" }                                        # the source of truth (UX/US/FR/CN/DC/IC/SC)
-      - { path: .appweaver/DESIGN-FORMAT.md }                            # the design-doc contract + its frontend lane variant
-      - { path: .appweaver/memory/constitution.ui.md, optional: true }   # the lane's UX-* base, reversed by onboard from this same UI
-      - { path: knowledge/architecture/frontend.md, optional: true }     # the as-built UI architecture + the SHARED surface no slice owns
-      - { path: "{{service_design}}", optional: true }                   # §5 ONLY — the service's published surface, never its internals
-  - id: gen_ui_design_brownfield
-    condition: "{{ui_design_mode}} == bootstrap_bf"
-    action: agent_author
-    output_target: { type: file, path: "{{ui_design_doc}}" }
-    task: |
-      Author the MASTER UI design (the target design.ui.md in context — it is this
-      project's CODE-DERIVED UI design template) for this NEW feature being added to an
-      EXISTING frontend, by filling the template from the feature spec + the loaded
-      frontend standards. It is the MEDIATOR between the spec and the components
-      `implement-ui` will generate. Guidance: {{USER_INPUT}}
-      Rules:
-      - THE SPEC IS THE ONLY DOMAIN INPUT. You have the spec + frontend standards + the
-        lane's as-built architecture reference, and NO domain rule files. The domain
-        arrives as spec ids only; an unavoidable new concept is an Assumption (DA-n).
-      - STRUCTURE FOLLOWS THE TEMPLATE AND THE LANE AS-BUILT, not a fixed screen
-        taxonomy. Keep the template's own section order and headings, and create one
-        component subsection per composition axis THIS feature actually needs, titled
-        with the lane's OWN name for it. ALIGN this feature to the app already there —
-        read the as-built architecture reference in context and MATCH its screen
-        organisation, its state and data-fetching placement and its styling approach, so
-        the feature slots in rather than introducing a second convention.
-      - KEEP THE NEUTRAL ANCHORS the template pins: the navigation/screen inventory, the
-        client-state table, the interaction-and-flow section, the cross-cutting table
-        and the traceability spine exist in every UI design, whatever the axes are
-        called. INTERACTION & FLOW and CROSS-CUTTING are NEVER omitted, however thin the
-        feature — loading, empty, error, permission-denied and in-flight states, focus
-        placement and keyboard reachability are where most UI defects live.
-      - REALISE THE SPEC'S EXPERIENCE CONTENT: every Experience Standard (UX-) gets a
-        traceability row (design.md excludes them by contract, so this is their only
-        home), every User Story a screen and a flow, every interaction-state FR- a flow
-        row. Realise the lifted constraints citing their ids — CN- as the authorization
-        surface and access conditions, DC- as what may not reach the client or its logs,
-        storage and URLs, IC- as binding rows, SC- as the performance decision.
-      - THE LANE BOUNDARY: bind against the service's PUBLISHED surface only — the
-        spec's IC- ids and, where design.md is in context, the API contracts it states.
-        Cite them; do not restate, re-derive or contradict them, and introduce no
-        server-side behaviour. What the experience needs and the surface lacks is a
-        contract delta raised back to the service lane, never a client workaround.
-      - CONSTITUTION-MANDATED CROSS-CUTTING with no per-feature spec id: apply it, and
-        log it as a DA-n citing the mandating principle ("per constitution.ui.md
-        UX-<n>"). Do not fabricate a spec id for it and do not leave it uncited.
-      - TECHNOLOGY-AGNOSTIC: name no framework, router, state library, component library
-        or styling approach — responsibilities, field shapes, events and states only.
-        Naming the lane's as-built CONVENTION is not naming a framework; naming the
-        library that implements it is. The framework binds at `implement-ui`.
-      - The header's Lane field is `{{lane_id}}`. That identifier is the ONLY thing you
-        are told about the lane: its framework and language are deliberately withheld,
-        because a design that knows them starts naming them.
-      - THE SHARED SURFACE (app shell, global layout, design system) belongs to no
-        feature. Cite it; do not copy it in and do not claim it here.
-      - Fill the traceability spine completely, both ways, and both ledgers —
-        Assumptions (DA-n) and Workarounds (WA-n), "None (as of v1.0)" when empty.
-      - This is v1.0: set the initial Change History row. No component code anywhere.
-
-  # ═══════════ HANDOFF — authoring only; the gate is a SEPARATE stage ════════
-  #   ⌛ /appweaver analyze-design-ui — the spec↔design.ui.md conformance gate (every
-  #     UX-/US-/FR- with an experience obligation realised here) — is not built yet.
-  #     Until it is, review §7 Traceability by hand before generating: it is the only
-  #     two-way check that a UX- did not fall between the two designs.
-  #   → /appweaver implement-ui generates the components from this document alone.
-
-  # 6. Post-execution hooks.
-  - id: resolve_post_hooks
-    action: execute_script
-    script: { ref: actions }
-    subcommand: resolve-hooks
-    args: ["--phase", "after_design_ui"]
-    outputs:
-      - { name: after_hooks, from: "$.hooks" }
-  - id: dispatch_post_hooks
-    action: dispatch_hooks
-    hooks_from_variable: after_hooks
-
-outputs:
-  feature_dir: "{{feature_dir}}"
-  ui_design_doc: "{{ui_design_doc}}"
-  lane_id: "{{lane_id}}"
-  lane_root: "{{lane_root}}"
-  version: "{{version}}"
-  next: "design.ui.md authored for the {{lane_id}} lane at {{ui_design_doc}}. Review §7 Traceability by hand — ⌛ /appweaver analyze-design-ui (the spec↔design.ui.md gate) is not built yet, and §7 is the only two-way check that a UX- did not fall between design.md and design.ui.md. Then /appweaver implement-ui, which generates the components from this document alone. A later change to it is a delta: ⌛ /appweaver delta-design-ui."