aw-spec-cli 0.1.14 → 0.1.16

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

@@ -0,0 +1,600 @@
+# =============================================================================
+# aw-spec-plan-ui (orchestrator) — the spec-anchored Plan phase (frontend lane)
+#
+# Authors and MAINTAINS the frontend lane's single high-level plan —
+# specs/<Aggregate>/frontend-plan.md — the experience twin of backend-plan.md and
+# the MEDIATOR between the spec and the components implement-ui generates (formerly
+# design.ui.md; the scaffold migrates a legacy design.ui.md by renaming it). Its
+# sections are the experience, not the four clean-architecture layers. See
+# .appweaver/DESIGN-FORMAT.md ("Frontend lane variant") +
+# .appweaver/templates/ui-design-template.md.
+#
+# WHY A SEPARATE COMMAND, NOT A UI BRANCH INSIDE `plan`. The two lanes are governed
+# by different rule sets (tech-rule-bindings gives each lane its own set for zero
+# mechanism change); a UI branch inside plan would put the lane's structure under
+# the service lane's rules and hand one phase the whole rule surface of both lanes.
+#
+# THREE MODES, resolved deterministically (self-detecting on the doc's existence):
+#   • bootstrap_gf (default) — no frontend-plan.md yet: author the master from the
+#     whole spec, shipped experience template (§0–§9).
+#   • bootstrap_bf — same, but onboard installed the code-derived ui-design-template
+#     override: author with the lane's AS-BUILT composition axes instead.
+#   • update — frontend-plan.md exists: conform it to what the spec's Change History
+#     ledger says moved SINCE THIS PLAN WAS LAST DERIVED, and nothing else. This
+#     replaces the former bootstrap-only refusal that routed to ⌛ delta-design-ui.
+#
+# TRACKING is identical to plan's: plan-check computes the state (fresh | untracked |
+# clean | behind | edited | edited_behind) and the moved ids; plan-stamp is the only
+# writer of the **Version** header, the doc's own Change History row and the body
+# hash in .aw-plan-track.frontend-plan.json — its OWN track file, so a backend plan
+# stamped at the same moment never contends with it. Hand edits are refused unless accept_manual:true
+# folds them in. The model writes NO version anywhere.
+#
+# WHERE IT SITS. specify/sync-spec (⌛ sync-spec is not built yet; the hand route is
+# .appweaver/SPEC-EDIT-PROTOCOL.md) move the spec; the developer then runs plan (the
+# service lane) and plan-ui, which conform each lane's design to what moved. FE story
+# designs READ this document for the ids they carry and NEVER write back — nothing
+# merges into it, so it keeps exactly one writer. It is the FEATURE-LEVEL
+# ARCHITECTURAL CONFIRMATION for the experience, with the concrete component-level
+# work left to the per-story passes.
+#
+# IT READS THE CODE — ITS OWN LANE'S. concept-coverage resolves the feature's OKF concept
+# to the `ui_source_files` realising its UI today (the service lane's `source_files` is a
+# different key and a different tree) and the authoring steps declare `tools: Read`, so a plan over
+# an existing frontend ADJUSTS to the composition, naming and state handling actually
+# there. The code is the what-exists authority; the spec stays the only authority on
+# required behaviour. source_count 0 = greenfield, and the phase never blocks on it.
+#
+# IT CONSUMES THE INTERFACE LOG — it never writes one. specs/<Aggregate>/interfaces.md
+# is the service lane's published surface, published by /appweaver plan and APPEND-ONLY:
+# §5 Contract Binding binds to the LATEST entry per interface (a `supersedes:` entry
+# replaces the one it names), cited BY IF- id, never restated. A `proposed` entry is
+# the designed contract and is bindable. What the experience needs and the surface
+# lacks is a CONTRACT DELTA raised back to the service lane, never a client workaround.
+#
+# Launch:  /appweaver plan-ui [guidance]        (accept_manual:true folds hand edits in)
+# Prereq:  /appweaver specify; /appweaver plan (so interfaces.md exists to bind
+#          against); a frontend lane declared via /appweaver select-stack
+# =============================================================================
+
+name: aw-spec-plan-ui
+description: "Author or update the frontend lane's high-level plan — specs/<Feature>/frontend-plan.md — from the spec: the experience twin of backend-plan.md, mediating between spec.md and the components implement-ui generates. Self-detects: no plan yet ⇒ bootstrap the master (shipped experience template, or the code-derived structure when onboard installed the ui-design-template override); plan exists ⇒ UPDATE — conform exactly the sections serving the ids the spec's Change History moved since this plan's derivation stamp, preserving the Assumptions/Workarounds/Change History ledgers. Realises the spec's UX- Experience Standards, which backend-plan.md excludes by contract; the service lane enters only at §5 Contract Binding, CONSUMING specs/<Feature>/interfaces.md — the append-only interface log /appweaver plan publishes, latest entry per id — cited by IF- id and never written to by this lane. Tracking is script-owned (plan-check / plan-stamp); hand edits are refused unless accept_manual folds them in. Technology-agnostic: the stack binds at implement-ui."
+version: 2.1.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional plan guidance (flow preferences, screen decomposition hints, constraints).
+    required: false
+    bind: USER_INPUT
+  accept_manual:
+    description: "true ⇒ a hand-edited plan (tracking state edited/edited_behind) is folded in instead of refused: the update keeps the manual edits' intent, reconciles them with the spec, and the stamp re-baselines."
+    required: false
+    bind: ACCEPT_MANUAL
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+  xref:
+    sh:  .appweaver/scripts/bash/aw-xref.sh
+    ps1: .appweaver/scripts/powershell/aw-xref.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-plan-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:
+  source_csv: ""                   # concept-coverage — the UI files realising this feature today
+  source_count: "0"                # 0 ⇒ greenfield: no frontend code for this feature yet
+  okf_concept: ""                  # the feature's OKF concept doc
+  ui_plan_mode: "bootstrap_gf"     # resolved below → bootstrap_gf | bootstrap_bf | update
+  ui_plan_created: "false"         # scaffold.created — true ⇒ the doc was absent ⇒ bootstrap
+  ui_plan_migrated: "false"        # scaffold renamed a legacy design.ui.md into frontend-plan.md this run
+  track_state: ""                  # plan-check → fresh | untracked | clean | behind | edited | edited_behind
+  derived_version: ""
+  current_version: ""
+  changed_csv: ""
+  changed_summary: ""
+  manual_ok: "true"                # false ⇒ hand edits present and accept_manual not given
+  plan_stale: "true"               # false ⇒ update mode with nothing to do (clean) — friendly stop
+  stamp_ok: "false"
+  stamp_error: ""
+
+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-plan-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 plan. Run /appweaver select-stack and declare the UI stack plus its source path, then re-run plan-ui. A project that genuinely has no UI plans the service lane alone with /appweaver plan."
+
+  # 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" }          # legacy name — a repo not yet migrated
+      - { name: service_plan,     from: "$.backend_plan_file" }     # the service lane's plan (post-rename)
+
+  - 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 plan-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 frontend-plan.md realises."
+
+  # 1b. The spec's own ledger tripwire — a plan derived from an unledgered spec
+  #     stamps a baseline the ledger cannot name (same fence as plan's).
+  - id: spec_guard
+    action: include
+    module: .appweaver/orchestrator/modules/spec-state-gate.orch.yaml
+    with: { command: "/appweaver plan-ui" }
+
+  # 2. Scaffold frontend-plan.md (idempotent). --lane frontend resolves the pair
+  #    ui-design-template → frontend-plan.md, and MIGRATES a legacy design.ui.md by
+  #    renaming it (created=false, migrated=true) — one document, never two.
+  - id: ui_plan_scaffold
+    action: execute_script
+    script: { ref: actions }
+    subcommand: design-scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--lane", "frontend"]
+    outputs:
+      - { name: ui_plan_doc,      from: "$.design_doc" }
+      - { name: ui_override,      from: "$.override_active" }   # true ⇒ onboard installed the code-derived template
+      - { name: ui_plan_created,  from: "$.created" }
+      - { name: ui_plan_migrated, from: "$.migrated" }
+
+  # 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_plan_mode: "bootstrap_bf" }
+  - id: mode_update
+    condition: "{{ui_plan_created}} == false"
+    action: set
+    vars: { ui_plan_mode: "update" }
+
+  # 3. Tracking: what moved since this plan was derived, and whether the doc was
+  #    hand-edited since its stamp. Same machinery and fences as plan's.
+  - id: plan_track
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-check
+    args: ["--feature-dir", "{{feature_dir}}", "--doc", "{{ui_plan_doc}}"]
+    outputs:
+      - { name: track_state,     from: "$.state" }
+      - { name: derived_version, from: "$.derived_version" }
+      - { name: current_version, from: "$.current_version" }
+      - { name: changed_csv,     from: "$.changed_csv" }
+      - { name: changed_summary, from: "$.changed_summary" }
+  - id: manual_flag_edited
+    condition: "{{track_state}} == edited"
+    action: set
+    vars: { manual_ok: "false" }
+  - id: manual_flag_edited_behind
+    condition: "{{track_state}} == edited_behind"
+    action: set
+    vars: { manual_ok: "false" }
+  - id: manual_accept
+    condition: "{{ACCEPT_MANUAL}} == true"
+    action: set
+    vars: { manual_ok: "true" }
+  - id: manual_fence
+    action: verify_context
+    require_true: manual_ok
+    on_false: stop
+    on_false_message: "frontend-plan.md was hand-edited since its last stamp (tracking state: {{track_state}}). Re-run plan-ui with accept_manual:true to fold the edits in (kept, reconciled with the spec, recorded in the ledgers, re-baselined) — or restore the document to its stamped state."
+  - id: clean_flag
+    condition: "{{track_state}} == clean"
+    action: set
+    vars: { plan_stale: "false" }
+  - id: clean_stop
+    action: verify_context
+    require_true: plan_stale
+    on_false: stop
+    on_false_message: "frontend-plan.md is in step with spec {{current_version}} — nothing to update. If the PLAN is wrong and the spec is right, hand-edit frontend-plan.md and re-run /appweaver plan-ui with accept_manual: true — that is what tells this command to keep the edit's intent and reconcile it rather than treat it as drift; without the flag the manual fence stops the run after the edit is already on disk."
+
+  # 5. Pre-execution hooks.
+  # THE CODE — THIS LANE'S. The UI plan is an architectural confirmation too, so it must
+  # know what this feature's experience already looks like on disk. concept-COVERAGE, not
+  # concept-paths: a feature has ONE OKF concept holding both lanes' file lists under
+  # different keys, and concept-paths returns the SERVICE lane's `source_files`. Reading it
+  # here planned the frontend against the backend's tree — a feature with a built frontend
+  # and no backend was planned as greenfield, and one with both handed the UI author the
+  # service lane's files to adjust to. concept-coverage splits the two and this binds
+  # `ui_source_files`. A PATH LIST, not inlined content (E60). on_error: continue — a
+  # greenfield feature has no concept doc and must never be blocked by one;
+  # source_count 0 is the greenfield signal the tasks read.
+  - id: concept_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: concept-coverage
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: source_csv,   from: "$.frontend_csv" }
+      - { name: source_count, from: "$.frontend_count" }
+      - { name: okf_concept,  from: "$.concept" }
+
+  - 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_plan
+    condition: "{{ui_plan_mode}} == bootstrap_gf"
+    action: build_context
+    context:
+      - { path: "{{ui_plan_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: "{{feature_dir}}/interfaces.md", optional: true }         # THE CONTRACT — the service lane's published surface, latest entry per id wins
+      - { path: "{{okf_concept}}", optional: true }                       # the feature's OKF concept: use-case log + source map
+      - { path: "{{service_plan}}", optional: true }                     # §5 ONLY — the service's structure; its API section only CITES the log
+      - { path: "{{service_design}}", optional: true }                   # the same surface under its legacy name (unmigrated repo)
+  - id: gen_ui_plan
+    condition: "{{ui_plan_mode}} == bootstrap_gf"
+    action: agent_author
+    tools: Read   # the current frontend code arrives as {{source_csv}} paths, not inlined
+    output_target: { type: file, path: "{{ui_plan_doc}}" }
+    task: |
+      Author the MASTER UI plan (the target frontend-plan.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).
+      - THE CODE IS THE WHAT-EXISTS AUTHORITY, and it is a DIFFERENT authority from the
+        spec. {{source_count}} file(s) realise this feature's experience today; read the
+        ones that bear on what you are deciding and ADJUST this plan to the composition,
+        naming and state handling that are actually there rather than to an idealised
+        shape. An empty list is greenfield — design from a clean slate and say so. The
+        code NEVER overrides the spec on required behaviour and introduces no rule the
+        spec omits: code contradicting the spec is recorded as a DA-n and designed to
+        the SPEC. A deliberate divergence from the as-built is a WA-n with its trigger.
+          {{source_csv}}
+      - 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 — backend-plan.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 FR- with a user-facing surface gets a screen home in §1 and a flow in
+          §4. Such an FR- with no screen is a coverage failure. (Stories live in
+          stories/ and never appear in this document — it traces to requirements.)
+        • 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, AND `interfaces.md` IS THE CONTRACT. The service
+        lane's published surface lives in that append-only log, which /appweaver plan
+        writes: bind against the LATEST entry per interface — an entry naming an
+        earlier id in `supersedes:` replaces it — plus the spec's IC- ids. CITE those
+        entries BY IF- id; do NOT restate, re-derive or contradict them, and introduce
+        NO server-side behaviour, persistence assumption or handler detail. An entry at
+        `status: proposed` is the designed contract and IS bindable; note the status
+        where it matters. NEVER WRITE TO THE LOG — this lane consumes it. 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 the log is absent (the service lane has not planned this
+        feature yet), bind from the spec's IC- surface and record that as a §8 DA-n
+        saying so.
+      - 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-, every FR- with a user-facing surface, and 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)".
+      - Complete the template's INITIAL Change History row, and write NO other version
+        anywhere — the stamp step owns the **Version** header. 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_plan_brownfield
+    condition: "{{ui_plan_mode}} == bootstrap_bf"
+    action: build_context
+    context:
+      - { path: "{{ui_plan_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: "{{feature_dir}}/interfaces.md", optional: true }         # THE CONTRACT — the service lane's published surface, latest entry per id wins
+      - { path: "{{okf_concept}}", optional: true }                       # the feature's OKF concept: use-case log + source map
+      - { path: "{{service_plan}}", optional: true }                     # §5 ONLY — the service's structure; its API section only CITES the log
+      - { path: "{{service_design}}", optional: true }                   # the same surface under its legacy name (unmigrated repo)
+  - id: gen_ui_plan_brownfield
+    condition: "{{ui_plan_mode}} == bootstrap_bf"
+    action: agent_author
+    tools: Read   # the current frontend code arrives as {{source_csv}} paths, not inlined
+    output_target: { type: file, path: "{{ui_plan_doc}}" }
+    task: |
+      Author the MASTER UI plan (the target frontend-plan.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).
+      - THE CODE IS THE WHAT-EXISTS AUTHORITY, and it is a DIFFERENT authority from the
+        spec. {{source_count}} file(s) realise this feature's experience today; read the
+        ones that bear on what you are deciding and ADJUST this plan to the composition,
+        naming and state handling that are actually there rather than to an idealised
+        shape. An empty list is greenfield — design from a clean slate and say so. The
+        code NEVER overrides the spec on required behaviour and introduces no rule the
+        spec omits: code contradicting the spec is recorded as a DA-n and designed to
+        the SPEC. A deliberate divergence from the as-built is a WA-n with its trigger.
+          {{source_csv}}
+      - 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 (backend-plan.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, AND `interfaces.md` IS THE CONTRACT: bind against the
+        LATEST entry per interface in that append-only log (a `supersedes:` entry
+        replaces the one it names), plus the spec's IC- ids. Cite them BY IF- id; do
+        not restate, re-derive or contradict them, introduce no server-side behaviour,
+        and NEVER write to the log — this lane consumes it. What the experience needs
+        and the surface lacks is a contract delta raised back to the service lane,
+        never a client workaround. Where the log is absent, bind from the spec's IC-
+        surface and record a DA-n saying so.
+      - 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.
+      - Complete the template's INITIAL Change History row, and write NO other version
+        anywhere — the stamp step owns the **Version** header. No component code anywhere.
+
+  # ══════════════════ UPDATE — conform the existing plan to the moved spec ═════
+  # The work list is COMPUTED, never guessed: the ledger rows above this plan's
+  # derivation stamp name exactly the ids to conform. Everything else stays
+  # byte-identical.
+  - id: ctx_ui_plan_update
+    condition: "{{ui_plan_mode}} == update"
+    action: build_context
+    context:
+      - { path: "{{ui_plan_doc}}" }                                      # the CURRENT plan — the document being conformed
+      - { path: "{{spec_file}}" }                                        # the source of truth at {{current_version}}
+      - { 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
+      - { path: knowledge/architecture/frontend.md, optional: true }     # brownfield repos: the as-built UI architecture
+      - { path: "{{feature_dir}}/interfaces.md", optional: true }         # THE CONTRACT — the service lane's published surface, latest entry per id wins
+      - { path: "{{okf_concept}}", optional: true }                       # the feature's OKF concept: use-case log + source map
+      - { path: "{{service_plan}}", optional: true }                     # §5 ONLY — the service's structure; its API section only CITES the log
+      - { path: "{{service_design}}", optional: true }                   # the same surface under its legacy name (unmigrated repo)
+  - id: gen_ui_plan_update
+    condition: "{{ui_plan_mode}} == update"
+    action: agent_author
+    tools: Read   # the current frontend code arrives as {{source_csv}} paths, not inlined
+    output_target: { type: file, path: "{{ui_plan_doc}}" }
+    task: |
+      UPDATE the master UI plan (the target frontend-plan.md in context) so it
+      conforms to the CURRENT spec. Tracking state: {{track_state}}. The spec moved
+      from {{derived_version}} (this plan's derivation) to {{current_version}}; the
+      ledger rows above the derivation name what moved:
+        ids:     {{changed_csv}}
+        changes: {{changed_summary}}
+      Guidance: {{USER_INPUT}}
+      Rules:
+      - SCOPE IS THE COMPUTED WORK LIST. Rework ONLY the screens, flows, state rows,
+        binding rows, cross-cutting rows and traceability rows that realise the ids
+        above. Every other line stays BYTE-IDENTICAL; an unrelated "improvement" is
+        drift. EXCEPTION — tracking state `untracked`: this document has no baseline
+        (a migrated legacy design.ui.md), so reconcile the WHOLE plan to the spec
+        once; the stamp then baselines it.
+      - accept_manual: {{ACCEPT_MANUAL}}. When true, the document carries hand edits
+        that were deliberately accepted: KEEP their intent, reconcile them with the
+        spec, and record each kept deviation honestly — a new concept as an
+        Assumptions DA-n, a deliberate shortcut as a Workarounds WA-n. Never silently
+        revert a hand edit.
+      - AN ID THE SPEC NO LONGER DEFINES LOSES ITS REALISATION; an id whose wording
+        moved is re-realised from the spec's CURRENT text — the spec is the wording.
+        A UX- is THIS document's to realise: a moved UX- with no home here after the
+        update is a DROPPED requirement.
+      - AN ID THE SPEC HAS NEWLY DEFINED GAINS ONE. An id in the work list that NO
+        existing section realises is an ADDITION: give it a home in the sections that
+        realise it and a traceability row like any other. The scope rule above says
+        which sections may be touched; it does not say a new requirement may not be
+        designed, and reading it that way would let every added UX- or FR- with a
+        user-facing surface select nothing to rework and land unrealised.
+      - THE CODE IS THE WHAT-EXISTS AUTHORITY, and it is a DIFFERENT authority from the
+        spec. {{source_count}} file(s) realise this feature's experience today; re-read the
+        ones the moved ids touch (code state is read FRESH every run, never assumed) and ADJUST this plan to the composition,
+        naming and state handling that are actually there rather than to an idealised
+        shape. An empty list is greenfield — design from a clean slate and say so. The
+        code NEVER overrides the spec on required behaviour and introduces no rule the
+        spec omits: code contradicting the spec is recorded as a DA-n and designed to
+        the SPEC. A deliberate divergence from the as-built is a WA-n with its trigger.
+          {{source_csv}}
+      - THE SPEC IS THE ONLY DOMAIN INPUT, and §5 stays the lane boundary: bind
+        against `interfaces.md` — the LATEST entry per interface, cited by IF- id —
+        introduce no server-side behaviour, and never write to the log. A moved id
+        whose interface changed appears there as a SUPERSEDING entry: rebind §5 to it.
+        What the experience needs and the surface lacks is a contract delta raised
+        back to the service lane.
+      - PRESERVE THE LEDGERS: Assumptions, Workarounds and Change History keep every
+        existing entry and their numbering — append, never rewrite. Write NO version
+        numbers anywhere and ADD NO Change History row: the stamp step appends the
+        row and moves the **Version** header.
+      - TRACEABILITY STAYS COMPLETE both ways after the update; TECHNOLOGY-AGNOSTIC,
+        no component code, same contract as at bootstrap.
+
+  # 5. STAMP — the only writer of the plan's version identity; refuses (no baseline)
+  #    if the write dropped the Change History section.
+  - id: stamp_bootstrap
+    condition: "{{ui_plan_mode}} != update"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-stamp
+    args: ["--feature-dir", "{{feature_dir}}", "--doc", "{{ui_plan_doc}}", "--no-row"]
+    outputs:
+      - { name: stamp_ok,        from: "$.ok" }
+      - { name: stamp_error,     from: "$.error" }
+      - { name: current_version, from: "$.version" }
+  - id: stamp_update
+    condition: "{{ui_plan_mode}} == update"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-stamp
+    args: ["--feature-dir", "{{feature_dir}}", "--doc", "{{ui_plan_doc}}", "--ids", "{{changed_csv}}", "--note", "Conformed to spec {{current_version}}"]
+    outputs:
+      - { name: stamp_ok,    from: "$.ok" }
+      - { name: stamp_error, from: "$.error" }
+  - id: stamp_fence
+    action: verify_context
+    require_true: stamp_ok
+    on_false: stop
+    on_false_message: "plan-stamp refused: {{stamp_error}} — frontend-plan.md has been written but NOT baselined. Restore the missing ledger section, then re-run plan-ui (or plan-stamp) to record the baseline."
+
+  # ═══════════ HANDOFF — authoring only; the gate is a SEPARATE stage ════════
+  #   → /appweaver analyze-design gates this write. It is ONE command over BOTH
+  #     lanes, not a per-lane pair: the coverage question spans them (a UX- has its
+  #     only home here, a BR- only in backend-plan.md, an FR- with a surface needs
+  #     both), so no per-lane gate could answer it. It reads §7 Traceability as the
+  #     two-way spine and refuses to certify a plan the spec has moved past.
+  #   → /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_plan_doc: "{{ui_plan_doc}}"
+  ui_plan_mode: "{{ui_plan_mode}}"
+  source_files_read: "{{source_count}}"
+  migrated_legacy_design: "{{ui_plan_migrated}}"
+  lane_id: "{{lane_id}}"
+  lane_root: "{{lane_root}}"
+  derived_from_spec: "{{current_version}}"
+  conformed_ids: "{{changed_csv}}"
+  next: "frontend-plan.md written for the {{lane_id}} lane at {{ui_plan_doc}} (mode: {{ui_plan_mode}}). Gate this write: /appweaver analyze-design — one command over BOTH lanes, which is what proves no UX- fell between them; it reads §7 Traceability as the two-way spine. CHECK §5 CONTRACT BINDING: it binds to interfaces.md, which /appweaver plan publishes — if that log was absent this run, §5 was bound from the spec's IC- ids alone and a DA-n says so, which means running plan first and re-running this command is what turns an assumption into the real contract. Contract deltas needed goes back to the service lane, never into the client. source_files_read {{source_count}} is how many existing UI files this plan was written against; 0 means greenfield. Then /appweaver implement-ui."