aw-spec-cli 0.1.14 → 0.1.16

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

@@ -1,52 +1,58 @@
 # =============================================================================
-# aw-spec-implement-ui (orchestrator) — model-driven UI generation from design.ui.md
+# aw-spec-implement-ui (orchestrator) — UI generation from ONE STORY'S DESIGN
 #
-# The frontend lane's Implement phase: GENERATE the screens, components, client state
-# and paired tests for the aggregate STRICTLY from its design.ui.md — the mediator
-# between the spec and the lane's code. It is the twin of `implement`, and it keeps the
-# same contract, one lane over:
+# The frontend lane's executable end of the story loop: GENERATE the screens,
+# components, client state and paired tests for ONE STORY, strictly from the LATEST
+# design pass in that story's own UI design —
+# specs/<F>/stories/<ID>/story-frontend-plan.md. It is the twin of `implement`, one
+# lane over, and keeps the same contract:
 #
-#   • DESIGN-ONLY. implement-ui does NOT read spec.md. The design is the complete,
-#     authoritative source for WHAT to build; anything missing from it is fixed in
-#     design-ui, never compensated for here from the spec or from memory.
-#   • THE FRAMEWORK BINDS HERE. design.ui.md is technology-agnostic — a "component" is
-#     a responsibility, its inputs are field shapes, its states are named. The actual
-#     framework, router, state library, component library and styling approach come
-#     from constitution.ui.md + the lane declaration + this command's rule set.
-#   • ONE SUBTREE. The lane owns the source path .appweaver/stacks.json declares for it,
-#     and nothing outside it. A file written elsewhere belongs to the service lane or
-#     to no lane at all.
+#   • ONE SLICE, NOT THE FEATURE. The pass names the files it changes; this phase edits
+#     an existing tree, creating only what the pass says is new, and MERGES its files
+#     into the feature's OKF concept rather than replacing the list.
+#   • DESIGN-ONLY. spec.md is not a generation input. It is read once, AFTER the code
+#     exists, by a read-only acceptance check that reports and never repairs.
+#   • THE FRAMEWORK BINDS HERE. The design is technology-agnostic — a "component" is a
+#     responsibility, its inputs are field shapes, its states are named. The framework,
+#     router, state library, component library and styling approach come from
+#     constitution.ui.md + the lane declaration + this command's rule set.
+#   • ONE SUBTREE. The lane owns the source path .appweaver/stacks.json declares for it
+#     and nothing outside it. A file written elsewhere belongs to the service lane.
+#
+# THE UI LANE CONSUMES THE CONTRACT; IT NEVER DEFINES ONE. interfaces.md is the
+# published surface and the pass binds to it by IF- id. A contract this slice needs that
+# the log does not carry is a DEFECT to surface — never an endpoint to invent, and never
+# a reason to reach into the service lane's code. Where the SAME story has a service
+# design it is in context too, as the newer word on what that surface will be.
 #
 # WHY A SEPARATE COMMAND, NOT A UI BRANCH INSIDE `implement`. The two lanes take their
 # code-generation rules from different map headings and write into disjoint subtrees.
 # Keying the rule maps on `## /aw-spec-implement-ui` gives the lane its own rule set for
 # zero mechanism change; a UI branch inside `implement` would generate frontend code
-# under the service lane's standards.
-#
-# Prereqs: /appweaver design-ui (the UI design), and a frontend project scaffolded under
-# the lane's own source path — implement-ui GENERATES into that tree, so with no project
-# there is nowhere to place the files. The project gate is deliberately LANE-SCOPED: a
-# manifest found only elsewhere in the repository is the service lane's, and accepting
-# it is how a frontend that was never built reports green.
+# under the service lane's standards. (`story-plan` designs BOTH lanes in one run
+# because everything ahead of its authoring step is shared; here nothing is — the
+# lane, the subtree, the rules and the OKF key all differ.)
 #
-# ⌛ /appweaver analyze-design-ui — the spec↔design.ui.md conformance gate that would
-# run between design-ui and this phase — is not built yet. Until it is, the two-way
-# check that no UX-/US- fell between the two designs is design.ui.md §7 read by hand.
+# GATES (all loud, all before any write): the frontend lane declared with its source
+# path; a project scaffolded under THAT path specifically — a manifest found only
+# elsewhere is the service lane's, and accepting it is how a frontend that was never
+# built reports green; an active feature; an OPEN story; and that story having a UI
+# design at all. A design behind the current spec, or a story the spec has moved past,
+# is ANNOUNCED, never refused; the route out of both is named.
 #
-# Next: /appweaver build (compiles every declared lane, this one included).
-#
-# Launch:  /appweaver implement-ui [strategy] [guidance]
+# Launch:  /appweaver implement-ui [<story-id>] [guidance]     (asks when ambiguous)
+# Prereq:  /appweaver story-plan (the story's UI design)  ·  Next: /appweaver build
 # =============================================================================
 
 name: aw-spec-implement-ui
-description: Generate the frontend lane's screens, components, client state and paired tests STRICTLY from the aggregate's design.ui.md, bound to the declared UI stack and written only under that lane's source path. Model-driven and design-only — it does not read the spec, the same contract implement keeps for the service lane. The framework, router, state library and styling approach bind here from constitution.ui.md and the lane declaration; the design stays technology-agnostic. Merges the generated files into the feature's existing OKF concept rather than replacing the service lane's.
-version: 1.0.0
+description: "Generate the frontend lane's screens, components, client state and paired tests for ONE STORY, strictly from the LATEST design pass in stories/<ID>/story-frontend-plan.md, bound to the declared UI stack and written only under that lane's source path. Model-driven and design-only — the spec is never a generation input; it appears once afterwards in a read-only acceptance check that reports and never repairs. Consumes interfaces.md by IF- id and never publishes into it. Incremental by contract: it edits the lane's existing tree and MERGES its files into the feature's OKF concept under ui_source_files, so the service lane's list is untouched."
+version: 2.0.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
 inputs:
   user_input:
-    description: Optional implementation guidance (focus area, screen subset, framework hints).
+    description: Optional story id and/or implementation guidance (e.g. "Order-001 reuse the shared date picker").
     required: false
     bind: USER_INPUT
 
@@ -60,14 +66,73 @@ scripts:
 
 # Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). The lane's
 # FRONTEND code-generation rule files are CONFIGURATION, loaded per-command from
-# guardrails/projects/<project>/tech-rule-bindings.md under `## /aw-spec-implement-ui` by
-# the tech-select module. Per the rule-partition this phase loads NO domain rule file —
-# the domain reached the lane through spec → design.ui.md. The lane's ratified base
-# arrives via constitution.ui.md (referred to directly, as-is — NOT mapped).
-# (missing files skipped at assembly time)
+# guardrails/projects/<project>/tech-rule-bindings.md under `## /aw-spec-implement-ui`
+# by the tech-select module. Per the rule-partition this phase loads NO domain rule
+# file — the domain reached the lane through spec → frontend-plan.md → the story's
+# design pass. The lane's ratified base arrives via constitution.ui.md (referred to
+# directly, as-is — NOT mapped).
 standards:
   - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
 
+vars:
+  feature_dir: ""
+  spec_file: ""
+  # story resolution
+  any_open: "false"
+  open_ids: "[]"
+  digest: ""
+  resolved: "false"
+  needs_pick: "false"
+  pick_reason: ""
+  picked_story: ""
+  story: ""
+  story_path: ""
+  story_open: "false"
+  status_msg: ""
+  story_title: ""
+  exercises_csv: ""
+  constraints_csv: ""
+  current_version: ""
+  stale_csv: ""
+  stale_note: ""
+  story_dir: ""
+  adr_path: ""
+  if_path: ""
+  # the story's UI design (+ the SERVICE design of the same story, for the contract)
+  design_doc: ""
+  design_exists: "false"
+  design_pass: "0"
+  design_spec_version: ""
+  design_stale: "false"
+  # WHICH LANES story-plan designed and which it dropped. Absent on a story designed before
+  # the keys existed, which is why the default message below keeps both readings.
+  designed_lanes: ""
+  dropped_lanes: ""
+  lane_keys_present: "false"
+  fe_lane_dropped: "false"
+  no_design_msg: ""
+  # the analyze-design verdict — law 40's evidence. certified defaults FALSE so a probe that
+  # could not run fails CLOSED, and the message default carries a route for the same reason.
+  pass_plan_hash: ""
+  gate_status: ""
+  gate_certified: "false"
+  gate_aborted: "false"
+  gate_gap_refs: ""
+  gate_report: ""
+  gate_lane_sha: ""
+  gate_msg: "The analyze-design verdict could not be read, so this run cannot tell whether the feature plans were ever certified. Run /appweaver analyze-design, then re-run."
+  service_design_doc: ""
+  # the feature's current code, per lane (OKF)
+  okf_concept: ""
+  coverage_digest: ""
+  fe_source_csv: ""
+  fe_source_count: "0"
+  be_source_count: "0"
+  # generation + enrichment
+  files: ""
+  accept_ok: "true"
+  accept_gaps: ""
+
 workflow:
 
   # 0. FRONTEND code-generation rule files → sticky standards (configuration, not
@@ -78,45 +143,242 @@ workflow:
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
     with: { command: aw-spec-implement-ui }
 
-  # 1. Resolve the current feature + its UI design; require the DESIGN (this phase's
-  #    only input). No spec — the design is the authoritative source for WHAT to build.
+  # 1. The active feature. spec.md is resolved here for the acceptance check ONLY —
+  #    it is not a generation 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: ui_design_doc,    from: "$.ui_design_file" }
-      - { name: ui_design_exists, from: "$.ui_design_exists" }
-
+      - { name: feature_dir, from: "$.feature_dir" }
+      - { name: spec_file,   from: "$.spec_file" }
   - 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 implement-ui."
 
-  - id: verify_ui_design
+  # 1b. THE LEDGER FENCE — the same one implement carries, for the same two readings:
+  #     the staleness computation below and the acceptance pass at the end.
+  - id: spec_state_guard
+    action: include
+    module: .appweaver/orchestrator/modules/spec-state-gate.orch.yaml
+    with: { command: "/appweaver implement-ui" }
+
+  # 2. WHICH STORY — the same resolution story-plan and implement use.
+  - id: story_scan
+    action: execute_script
+    script: { ref: actions }
+    subcommand: story-plan-check
+    args: ["--feature-dir", "{{feature_dir}}", "--input", "{{USER_INPUT}}"]
+    outputs:
+      - { name: any_open,            from: "$.any_open" }
+      - { name: open_ids,            from: "$.open_ids" }
+      - { name: digest,              from: "$.digest" }
+      - { name: resolved,            from: "$.resolved" }
+      - { name: needs_pick,          from: "$.needs_pick" }
+      - { name: pick_reason,         from: "$.pick_reason" }
+      - { name: story,               from: "$.story" }
+      - { name: story_path,          from: "$.story_path" }
+      - { name: story_open,          from: "$.story_open" }
+      - { name: status_msg,          from: "$.status_msg" }
+      - { name: story_title,         from: "$.story_title" }
+      - { name: exercises_csv,       from: "$.exercises_csv" }
+      - { name: constraints_csv,     from: "$.constraints_csv" }
+      - { name: current_version,     from: "$.current_version" }
+      - { name: stale_csv,           from: "$.stale_csv" }
+      - { name: stale_note,          from: "$.stale_note" }
+      - { name: story_dir,           from: "$.story_dir" }
+      - { name: adr_path,            from: "$.adr_path" }
+      - { name: if_path,             from: "$.if_path" }
+      - { name: design_doc,          from: "$.fe_doc_path" }
+      - { name: design_exists,       from: "$.fe_doc_exists" }
+      - { name: design_pass,         from: "$.fe_last_pass" }
+      - { name: design_spec_version, from: "$.fe_doc_spec_version" }
+      - { name: design_stale,        from: "$.fe_doc_stale" }
+      - { name: pass_plan_hash,      from: "$.fe_pass_plan_hash" }
+      - { name: designed_lanes,      from: "$.designed_lanes_csv" }
+      - { name: dropped_lanes,       from: "$.dropped_lanes_csv" }
+      - { name: lane_keys_present,   from: "$.lane_keys_present" }
+      - { name: fe_lane_dropped,     from: "$.fe_lane_dropped" }
+      - { name: service_design_doc,  from: "$.be_doc_path" }
+  - id: require_open_backlog
     action: verify_context
-    require_true: ui_design_exists
+    require_true: any_open
     on_false: stop
-    on_false_message: "No design.ui.md for the current feature. Run /appweaver design-ui first — implement-ui generates STRICTLY from the UI design, and there is nothing else it may read. Review its §7 Traceability before generating: ⌛ /appweaver analyze-design-ui, the spec↔design.ui.md gate, is not built yet."
+    on_false_message: "No open stories for this feature — there is nothing to implement. Stories are minted by /appweaver specify (bootstrap) and /appweaver sync-stories (when the spec moves)."
+  - id: ask_story
+    condition: "{{needs_pick}} == true"
+    action: ask
+    prompt: |
+      Which story is this UI implementation for? ({{pick_reason}})
 
-  # 1a. Require the FRONTEND LANE and its source path. This phase writes code, and the
-  #     lane's root is the only subtree it may write into — so this runs before the
-  #     project gate, which searches that subtree.
+      {{digest}}
+    options_from: "{{open_ids}}"
+    answer_key: picked_story
+    answer_var: picked_story
+  - id: story_pick_check
+    condition: "{{needs_pick}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: story-plan-check
+    args: ["--feature-dir", "{{feature_dir}}", "--story", "{{picked_story}}"]
+    outputs:
+      - { name: resolved,            from: "$.resolved" }
+      - { name: story,               from: "$.story" }
+      - { name: story_path,          from: "$.story_path" }
+      - { name: story_open,          from: "$.story_open" }
+      - { name: status_msg,          from: "$.status_msg" }
+      - { name: story_title,         from: "$.story_title" }
+      - { name: exercises_csv,       from: "$.exercises_csv" }
+      - { name: constraints_csv,     from: "$.constraints_csv" }
+      - { name: stale_csv,           from: "$.stale_csv" }
+      - { name: stale_note,          from: "$.stale_note" }
+      - { name: story_dir,           from: "$.story_dir" }
+      - { name: design_doc,          from: "$.fe_doc_path" }
+      - { name: design_exists,       from: "$.fe_doc_exists" }
+      - { name: design_pass,         from: "$.fe_last_pass" }
+      - { name: design_spec_version, from: "$.fe_doc_spec_version" }
+      - { name: design_stale,        from: "$.fe_doc_stale" }
+      - { name: pass_plan_hash,      from: "$.fe_pass_plan_hash" }
+      - { name: designed_lanes,      from: "$.designed_lanes_csv" }
+      - { name: dropped_lanes,       from: "$.dropped_lanes_csv" }
+      - { name: lane_keys_present,   from: "$.lane_keys_present" }
+      - { name: fe_lane_dropped,     from: "$.fe_lane_dropped" }
+      - { name: service_design_doc,  from: "$.be_doc_path" }
+  - id: require_story
+    action: verify_context
+    require_true: resolved
+    on_false: stop
+    on_false_message: |
+      Could not resolve a story from '{{picked_story}}'. Open stories:
+      {{digest}}
+      Re-run implement-ui naming one of them.
+  - id: require_open_story
+    action: verify_context
+    require_true: story_open
+    on_false: stop
+    on_false_message: "{{status_msg}}"
+
+  # 3. THE STORY MUST HAVE A UI DESIGN. A story with a service design and no UI one is
+  #    not a failure — it is a slice with no user-facing surface, and the message says
+  #    so rather than implying something is broken.
+  # WHICH OF THE TWO READINGS IT IS, where the story says. analyze-design STOPS on a lane
+  # whose plan is behind; story-plan DROPS it and designs the other — so one command later
+  # "this slice has no user-facing surface" and "the UI lane was out of scope when this was
+  # designed" are the same absence on disk, and the message below could only offer both.
+  # story-plan now stamps `designed_lanes:` and `dropped_lanes:`, so the answer is recorded.
+  # ORDERED SETS, most specific last. The default is the two-reading message, which stays
+  # exactly right for a story designed BEFORE those keys existed: it has neither, and a
+  # missing key must never be read as "no user-facing surface".
+  - id: no_design_msg_default
+    action: set
+    vars:
+      no_design_msg: "Story {{story}} has no UI design — {{story_dir}}/story-frontend-plan.md does not exist, and the story records no designed/dropped lanes (it was designed before the kit stamped them). Either this slice has no user-facing surface (nothing to do here; run /appweaver implement for the service half), or the UI lane was out of scope when it was designed — a frontend lane that is undeclared, or a frontend-plan.md that is missing or behind the spec, drops that lane from a story-plan run and says so. Fix whichever it was and re-run /appweaver story-plan {{story}}."
+  - id: no_design_msg_no_surface
+    condition: "{{lane_keys_present}} == true"
+    action: set
+    vars:
+      no_design_msg: "Story {{story}} has no UI design and its UI lane was NOT dropped — the story records designed lanes [{{designed_lanes}}] and dropped lanes [{{dropped_lanes}}], so this slice genuinely has no user-facing surface. There is nothing for implement-ui to do here; run /appweaver implement for the service half. If it SHOULD have a UI surface, declare the frontend lane and re-run /appweaver story-plan {{story}}."
+  - id: no_design_msg_dropped
+    condition: "{{fe_lane_dropped}} == true"
+    action: set
+    vars:
+      no_design_msg: "Story {{story}} has no UI design because the UI LANE WAS DROPPED when it was designed — the story records dropped lanes [{{dropped_lanes}}]. This is not a slice without a user-facing surface; it is one whose UI half was never designed, because the frontend lane was undeclared or frontend-plan.md was missing or behind the spec. Fix that lane (/appweaver plan-ui, or declare it with /appweaver select-stack), then re-run /appweaver story-plan {{story}} and this command."
+
+  - id: require_design
+    action: verify_context
+    require_true: design_exists
+    on_false: stop
+    on_false_message: "{{no_design_msg}}"
+
+  # 3a. Announced, never refused — the same contract implement keeps. design_stale is a
+  #     JSON boolean, so `condition:` does the deciding and the value gate is only the
+  #     vehicle that prints (law 43); stale_csv is a string and compares directly.
+  - id: design_stale_notice
+    condition: "{{design_stale}} == true"
+    action: verify_context
+    require_value: design_stale
+    equals: "false"
+    on_mismatch: continue
+    on_mismatch_message: "UI design pass {{design_pass}} was written against spec {{design_spec_version}} and the spec is now at {{current_version}}. Generating from it is not wrong — the move may not touch this story — but if it does, the code inherits a contract that no longer holds. Re-run /appweaver story-plan {{story}} to design against the current spec, or check the ids named below."
+  - id: story_stale_notice
+    action: verify_context
+    require_value: stale_csv
+    equals: ""
+    on_mismatch: continue
+    on_mismatch_message: "The spec has moved on ids THIS story carries: {{stale_csv}}. Whatever this run generates for them realises superseded wording. Consider /appweaver sync-stories to bring the backlog back in step, then /appweaver story-plan {{story}}, before building."
+
+  # ═══════ 3a-bis. LAW 40, THE LAST HOP — the plan this pass was designed against ═══════
+  # THREE HASHES, not two. story-plan proved the feature plan was certified in the shape it
+  # was in when this pass was designed, and story-plan-doc stamped that certified hash into
+  # the pass header. But a pass is written once and read forever: comparing only the CURRENT
+  # plan to the CURRENT verdict would let a pass designed against plan H1 still generate
+  # after the plan was edited to H2 and re-gated — which is precisely the case law 40 names,
+  # one level below where it was being checked.
+  #   pass hash        what this pass was designed against  (the story pass header)
+  #   verdict hash     what analyze-design last certified   (the gate verdict)
+  # A MISMATCH IS A STOP, at the same severity as never-gated: continuing ships code built
+  # to an architecture nobody approved. Per lane, and only for the lane this command builds.
+  - id: gate_verdict
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: gate-read
+    args: ["--feature-dir", "{{feature_dir}}", "--gate", "analyze-design"]
+    outputs:
+      - { name: gate_status,    from: "$.status" }
+      - { name: gate_certified, from: "$.certified" }
+      - { name: gate_aborted,   from: "$.aborted" }
+      - { name: gate_gap_refs,  from: "$.gap_refs_csv" }
+      - { name: gate_report,    from: "$.report" }
+      - { name: gate_lane_sha,  from: "$.frontend_sha256" }
+
+  # Three reasons, three routes; ordered sets, last match wins. Aborted is last because it
+  # also carries status "fail" — the red gate_result_open writes BEFORE any analysis — and
+  # sending someone to read gaps that were never found is the one wrong answer here.
+  - id: gate_msg_never
+    action: set
+    vars: { gate_msg: "The feature plans for this feature have never been certified: there is no analyze-design verdict beside them. Generation builds from a story pass that sits under an unapproved architecture. Run /appweaver analyze-design, then /appweaver story-plan {{story}}, then re-run /appweaver implement-ui." }
+  - id: gate_msg_red
+    condition: "{{gate_status}} == fail"
+    action: set
+    vars: { gate_msg: "The feature plans do NOT conform to the spec: analyze-design's last verdict is FAIL on {{gate_gap_refs}} (report: {{gate_report}}). Close those gaps before generating code beneath them, then re-run /appweaver implement-ui." }
+  - id: gate_msg_aborted
+    condition: "{{gate_aborted}} == true"
+    action: set
+    vars: { gate_msg: "The last analyze-design run STARTED and never reached a verdict — the red on disk is the one it writes before any analysis, so nothing was found and there are no gaps to read. The plans are UNCERTIFIED, not rejected. Run /appweaver analyze-design to completion, then re-run /appweaver implement-ui." }
+
+  - id: gate_certified_guard
+    action: verify_context
+    require_true: gate_certified
+    on_false: stop
+    on_false_message: "{{gate_msg}}"
+
+  # An EMPTY pass hash fails this, and that is correct: a pass written before the hash was
+  # stamped cannot say which plan shape it was designed against, so nothing can prove it was
+  # designed against the approved one. The route is the same either way — re-design.
+  - id: pass_plan_shape_guard
+    action: verify_context
+    require_value: pass_plan_hash
+    equals: "{{gate_lane_sha}}"
+    on_mismatch: stop
+    on_mismatch_message: "Design pass {{design_pass}} for story {{story}} was designed against a frontend plan that is NOT the one analyze-design currently certifies — the plan has been edited and re-gated since, or this pass predates plan-hash stamping and cannot say what it was designed against. Generating from it would build to an architecture nobody approved for this shape of the plan. Re-run /appweaver story-plan {{story}} to design against the currently certified plan, then re-run /appweaver implement-ui."
+
+  # 4. THE FRONTEND LANE and its source path — the only subtree this phase may write
+  #    into, resolved before the project gate that searches it.
   - id: lane_gate
     action: include
     module: .appweaver/orchestrator/modules/lane-gate.orch.yaml
     with: { require: frontend, command: "/appweaver implement-ui" }
 
-  # 1b. Require a frontend PROJECT under the LANE'S OWN path. Deterministic structure
-  #     gate: detect-project searches the lane subtree for an ecosystem manifest and
-  #     falls back to the whole repository when it finds none, reporting which scope
-  #     answered. THAT DISTINCTION IS THE GATE HERE. A repo-scope hit in a two-lane
-  #     project is the service lane's manifest, and accepting it is exactly the failure
-  #     the lane model exists to prevent — a frontend that was never scaffolded,
-  #     generated into anyway, reporting green.
+  # 5. Require a frontend PROJECT under the LANE'S OWN path. detect-project searches the
+  #    lane subtree first and falls back to the whole repository, reporting which scope
+  #    answered. THAT DISTINCTION IS THE GATE HERE. A repo-scope hit in a two-lane
+  #    project is the service lane's manifest, and accepting it is exactly the failure
+  #    the lane model exists to prevent — a frontend that was never scaffolded,
+  #    generated into anyway, reporting green.
   - id: detect_ui_project
     action: execute_script
     script: { ref: actions }
@@ -126,15 +388,31 @@ workflow:
       - { name: ui_project_present, from: "$.scaffolded" }
       - { name: project_markers,    from: "$.markers" }
       - { name: project_scope,      from: "$.scope" }
-
   - id: ui_project_gate
     action: verify_context
     require_value: project_scope
     equals: "lane"
     on_mismatch: stop
-    on_mismatch_message: "No frontend project found under the {{lane_id}} lane's source path `{{lane_source_path}}`. implement-ui GENERATES this feature's UI into an existing project tree, so one has to be scaffolded there first: run /appweaver foundation <FoundationName> <AppName> where a foundation bundle ships for {{lane_profile}}, or create the project with the stack's own tooling under that path. Any ecosystem manifest inside the lane's path marks it — package.json, go.mod, pyproject.toml, Cargo.toml, pom.xml, build.gradle(.kts) or .sln/.csproj. A manifest found elsewhere in the repository does NOT count: that one belongs to another lane, and generating this lane's code against it is how a frontend that was never built reports green."
+    on_mismatch_message: "No frontend project found under the {{lane_id}} lane's source path `{{lane_source_path}}`. implement-ui GENERATES this story's UI into an existing project tree, so one has to be scaffolded there first: run /appweaver foundation <FoundationName> <AppName> where a foundation bundle ships for this stack, or create the project with the stack's own tooling under that path. Any ecosystem manifest inside the lane's path marks it — package.json, go.mod, pyproject.toml, Cargo.toml, pom.xml, build.gradle(.kts) or .sln/.csproj. A manifest found elsewhere in the repository does NOT count: that one belongs to another lane, and generating this lane's code against it is how a frontend that was never built reports green."
 
-  # 2. Pre-execution hooks.
+  # 6. WHAT ALREADY EXISTS, per lane, from the feature's OKF concept. The UI list is
+  #    what this run edits; the service count tells the pass whether the contract it
+  #    binds to has been built yet. Advisory — a first UI story generates into a clean
+  #    tree and a missing bundle must never block generation.
+  - id: coverage
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: concept-coverage
+    args: ["--feature-dir", "{{feature_dir}}", "--ids", "{{exercises_csv}}"]
+    outputs:
+      - { name: okf_concept,     from: "$.concept" }
+      - { name: coverage_digest, from: "$.digest" }
+      - { name: fe_source_csv,   from: "$.frontend_csv" }
+      - { name: fe_source_count, from: "$.frontend_count" }
+      - { name: be_source_count, from: "$.backend_count" }
+
+  # 7. Pre-execution hooks.
   - id: resolve_pre_hooks
     action: execute_script
     script: { ref: actions }
@@ -146,81 +424,122 @@ workflow:
     action: dispatch_hooks
     hooks_from_variable: before_hooks
 
-  # 3. Model-driven generation: design.ui.md → screens, components, state + tests.
-  #    The design constrains WHAT to build; constitution.ui.md + the lane fix HOW.
-  #    The spec is deliberately NOT in context — the design is the single source here.
+  # ═══════════════════ GENERATION — one story's UI slice, one pass ═════════════
+  # The pass constrains WHAT to build; constitution.ui.md, the lane and the loaded
+  # standards fix HOW. spec.md is deliberately absent — the acceptance check below is
+  # where it gets its say.
   - id: ctx_generate
     action: build_context
+    vars:
+      story_id: "{{story}}"
+      story_title: "{{story_title}}"
+      exercises_csv: "{{exercises_csv}}"
+      constraints_csv: "{{constraints_csv}}"
+      pass_number: "{{design_pass}}"
+      coverage_digest: "{{coverage_digest}}"
+      ui_source_files_csv: "{{fe_source_csv}}"
+      ui_source_file_count: "{{fe_source_count}}"
+      stale_note: "{{stale_note}}"
     context:
-      - { path: "{{ui_design_doc}}" }
+      - { path: "{{design_doc}}" }                          # the story's UI design — the LATEST pass is the input
+      - { path: "{{story_path}}" }                          # the story's acceptance criteria — what "done" means
+      - { path: "{{if_path}}", optional: true }             # the PUBLISHED surface this slice binds to, by IF- id
+      - { path: "{{service_design_doc}}", optional: true }  # the SAME story's service design — the newer word on that surface
+      - { path: "{{adr_path}}", optional: true }            # ratified decisions — binding unless a pass supersedes them
       - { path: .appweaver/memory/constitution.ui.md, optional: true }   # the lane's ratified UX-* base — conventions, forbidden patterns, gates
   - id: generate
     action: agent_generate
-    tools: "Read,Write,Edit"
+    tools: "Read,Write,Edit"       # the existing UI code arrives as {{ui_source_files_csv}} paths, not inlined
     permission_mode: acceptEdits
     task: |
-      Generate the production UI code AND paired tests for this feature STRICTLY from
-      its design.ui.md (in context). The design is the complete, authoritative source of
-      WHAT to build — do NOT consult or infer from the spec. This phase is the HOME of
-      the framework-specific, lane-wide code-generation rules. Guidance: {{USER_INPUT}}
+      Implement story {{story_id}} — {{story_title}} — in the frontend lane, from
+      "## Design pass {{pass_number}}" of the UI story design in context.
+      Guidance: {{USER_INPUT}}
+
+      THAT PASS IS THE ONLY SOURCE OF WHAT TO BUILD. It is the LAST pass in the
+      document; every earlier pass is superseded history, and any of them may carry
+      hand edits that were deliberate. Read the last one and build exactly it. Do NOT
+      consult or infer from spec.md — it is not in context on purpose.
+
+      THIS IS ONE SLICE OF AN EXISTING FRONTEND, NOT THE WHOLE FEATURE.
+      - The pass's "### Screens & components" section names, file by file, what to
+        create and what to modify. Create ONLY the files it names as new; modify the
+        named existing files IN PLACE. Every other file belongs to work already done —
+        do not regenerate, reformat or "tidy" it.
+      - The story delivers {{exercises_csv}} and must satisfy {{constraints_csv}} — the
+        complete set of bounds the spec declares for this aggregate, stamped into the
+        story's frontmatter by the kit rather than transcribed by anyone. ALL of them
+        apply here: the UX- are yours to realise, and the CN-/DC-/IC- still bind what this
+        surface may show, send and store. Anything outside those ids is another story's
+        work, even if you can see it is missing.
+      - The code that already exists for this feature, per lane, is below. The UI files
+        ({{ui_source_file_count}} on disk) are yours to read before you edit; the
+        service list is there so you can see what the contract is actually backed by.
+
+      {{coverage_digest}}
+
+          {{ui_source_files_csv}}
+
+      BIND THE STACK: this lane is `{{lane_id}}` — {{lane_title}}, language
+      {{lane_language}} ({{lane_ecosystem}}), declared in .appweaver/stacks.json and
+      built with `{{lane_build}}`, tested with `{{lane_test}}`. Generate in THAT
+      framework and no other, using its idioms, its project layout and its test
+      framework. Take the router, state approach, component library, design system and
+      styling from the UI constitution + the loaded standards; the design is
+      technology-agnostic, so do not re-decide anything already fixed there. If the
+      loaded standards describe a DIFFERENT stack than the one above, the lane wins on
+      framework and layout — follow the standards' INTENT and STOP to surface the
+      mismatch in your summary.
+
+      WRITE ONLY UNDER `{{lane_source_path}}` — the source path the `{{lane_id}}` lane
+      declares. NEVER touch the service lane's code, not even to add a field the UI
+      wants: a gap in the service surface is a contract delta raised back to that lane,
+      not a file you edit. Do not create a parallel source tree because the layout
+      inside this one is unfamiliar; if the pass needs a place this subtree has no home
+      for, STOP and surface it.
+
       Rules:
-      - THE DESIGN IS THE ONLY DOMAIN INPUT. You have design.ui.md + the lane's
-        frontend standards, and NO domain rule files. Introduce NO domain rule,
-        identifier, terminology or behaviour the design does not state — everything
-        domain already passed through spec → design.ui.md. If a domain specific seems
-        missing, STOP and surface it; never invent it from memory.
-      - BIND THE STACK: this lane is `{{lane_id}}` — {{lane_title}}, language
-        {{lane_language}} ({{lane_ecosystem}}), declared in .appweaver/stacks.json and
-        built with `{{lane_build}}`, tested with `{{lane_test}}`. Generate in THAT
-        framework and no other, using its idioms, its project layout and its test
-        framework. Take the router, state approach, component library, design system and
-        styling from the UI constitution + the loaded standards; the design is
-        technology-agnostic, so do not re-decide anything already fixed there. If the
-        loaded standards describe a DIFFERENT stack than the one above, the lane wins on
-        framework and layout — follow the standards' INTENT and STOP to surface the
-        mismatch in your summary.
-      - WRITE ONLY UNDER `{{lane_source_path}}` — the source path the `{{lane_id}}` lane
-        declares. That subtree is this lane's; a file outside it belongs to the service
-        lane or to no lane. NEVER touch the service lane's code, not even to add a field
-        the UI wants: a gap in the service surface is a contract delta raised back to
-        that lane. Do not create a parallel source tree because the layout inside this
-        one is unfamiliar; if the design needs a place this subtree has no home for,
-        STOP and surface it.
+      - THE PASS IS THE ONLY DOMAIN INPUT. You have it, the story, and the lane's
+        frontend standards — and NO domain rule files. Introduce NO domain rule,
+        identifier, terminology or behaviour the pass does not state. If a domain
+        specific seems missing, STOP and surface it; never invent it from memory.
       - Follow the UI constitution's folder structure, naming conventions and forbidden
         patterns, plus the loaded standards, for HOW to structure, name and place files
-        WITHIN that subtree — the design says WHAT to build; these say HOW.
-      - REALISE EVERY DESIGN ELEMENT, changing nothing about WHAT it specifies:
-        • §1 — one route/screen per row, with the navigation shape and the access
-          conditions the row states.
-        • §2 — the client state exactly as owned and scoped there, including its
-          invalidation triggers. Anything the design lists under "what must NOT be held"
-          NEVER reaches client state, storage, the URL or telemetry.
-        • §3 — one component per row, with the responsibility, the input field shapes
-          and the events the design gives it. Compose the shared components the design
-          says it reuses; do not re-implement them.
-        • §4 — EVERY state in EVERY interaction row: loading, empty, error,
-          permission-denied and in-flight/disabled, plus the validation timing, the focus
-          and keyboard behaviour and the concurrency handling stated there. These are
-          requirements, not polish, and they are the first thing a generator drops.
-        • §5 — the service binding, through the lane's own client layer, with the write
-          semantics and rollback each row states.
-        • §6 — the cross-cutting decisions as code: what is hidden vs disabled,
-          accessibility obligations, localization, performance and offline behaviour.
+        WITHIN that subtree — the pass says WHAT to build; these say HOW.
+      - REALISE THE PASS EXACTLY, changing nothing about WHAT it specifies:
+        • its "### Approach" — the routes and screens it touches, and where this
+          slice's state lives. Anything the design says must NOT be held never reaches
+          client state, storage, the URL or telemetry.
+        • its "### Screens & components" — each component with the responsibility, the
+          input shapes and the events the pass gives it. Compose the shared components
+          it says it reuses; do not re-implement them.
+        • its "### Contract binding" — call each interface BY ITS IF- id as the pass
+          names it, with the request it states, and render EVERY state it lists:
+          in-flight, empty, error and the failure behaviour. These are requirements,
+          not polish, and they are the first thing a generator drops.
+      - THE CONTRACT IS NOT YOURS TO INVENT. interfaces.md (in context) is the
+        published surface; bind to the latest entry per id. If the pass names an
+        interface the log does not carry, STOP and surface it — do not invent an
+        endpoint, and do not reach into the service lane to add one. Where the SAME
+        story's service design is in context, it is the newer word on what that surface
+        will be; bind to it and say so in your summary.
       - THE CLIENT IS NOT AN AUTHORITY. A client-side validation or permission check
         restates a server rule for feedback; it never replaces it. Generate no
-        server-side behaviour, no persistence and no business rule evaluation here.
-      - Author a paired test for every screen, interaction and state the design names —
-        including the unwanted-behaviour states from §4 and an accessibility assertion
-        per interactive surface — and cite the spec id (UX-/US-/FR-/CN-/DC-/IC-/SC-)
-        from the design's §7 Traceability in each test. A snapshot alone is not a test.
-      - Do NOT add behaviour the design does not state, and do NOT omit any it does. If
-        the design looks wrong or incomplete, STOP and surface it (it is fixed in
-        design-ui) — never compensate from the spec or from memory.
+        server-side behaviour, no persistence and no business-rule evaluation here.
+      - ADRs are DECIDED — follow them. The pass may propose a superseding one; a
+        proposal is not yet ratified, so follow the pass and change nothing else.
+      - Author a paired test for every acceptance criterion in the story and every
+        behaviour the pass's "### Tests" section names — including the unwanted-state
+        cases from its contract binding and an accessibility assertion per interactive
+        surface — and cite the requirement id ({{exercises_csv}}, {{constraints_csv}})
+        each test exists for. A snapshot alone is not a test.
+      - Do NOT add behaviour the pass does not state, and do NOT omit any it does. If
+        the pass looks wrong or incomplete, STOP and surface it — it is fixed by
+        re-running /appweaver story-plan, never compensated for here.
       - This feature OWNS its files; never regenerate a file another feature owns, and
         do not modify the app shell, global layout or design system — they belong to no
         feature. If one of them has to change, STOP and surface it.
-      - Where generated code depends on a design Assumption (DA-n) or Workaround (WA-n),
-        mark it with a comment citing that id so it is easy to revisit later.
+      {{stale_note}}
     outputs:
       - { name: files, from: "$.files" }
 
@@ -228,24 +547,99 @@ workflow:
     action: verify_context
     require_non_empty: files
     on_empty: stop
-    on_empty_message: "No files generated. Ensure /appweaver design-ui produced a filled design.ui.md (not the empty template), then re-run."
-
-  # 3b. OKF knowledge — the feature has ONE concept across both lanes, so the UI files
-  #     JOIN it rather than replace it. --merge unions them with whatever is already
-  #     recorded; without it this run would erase the service lane's source_files, and
-  #     `implement` may have run before or after this one. The concept's Overview is
-  #     NOT re-authored here: it describes the aggregate and its invariants, which is
-  #     the service design's subject, and rewriting it from the UI design would trade a
-  #     domain description for an experience one.
+    on_empty_message: "No files generated for story {{story}}. Check that UI design pass {{design_pass}} in {{design_doc}} actually describes changes (a pass whose '### Screens & components' section is empty has nothing to build), then re-run — or re-run /appweaver story-plan {{story}} to design the slice properly first."
+
+  # 8. OKF — MERGE, into the UI LANE'S KEY. The feature has ONE concept across both
+  #    lanes: `--lane frontend` writes `ui_source_files`, so the service lane's
+  #    `source_files` is untouched whichever lane implements first, and `--merge` unions
+  #    this story's files with what the feature's earlier UI stories wrote. The
+  #    concept's Overview is NOT re-authored here: it describes the aggregate and its
+  #    invariants, which is the service design's subject, and rewriting it from a UI
+  #    slice would trade a domain description for an experience one.
   - id: xref_concept
     action: execute_script
     script: { ref: xref }
     subcommand: concept-upsert
-    args: ["--feature-dir", "{{feature_dir}}", "--source-files", "{{files}}", "--merge", "--origin", "greenfield"]
+    # --ids + --slice record WHICH REQUIREMENT this run's files realise, as Requirement
+    # Anchors rows in the concept. Both halves were already here and thrown away: the ids
+    # the story exercises, and the files just generated. Only `adopt` writes a
+    # source-map.md, so without this every id on a greenfield feature came back unanchored
+    # at analyze-slice and the trace pass had to read the whole tree to find out what
+    # implements what. Reconcile-on-write, keyed by slice + lane.
+    args: ["--feature-dir", "{{feature_dir}}", "--source-files", "{{files}}", "--merge", "--lane", "frontend", "--origin", "greenfield", "--ids", "{{exercises_csv}}", "--slice", "{{story}}"]
     outputs:
-      - { name: okf_concept, from: "$.concept" }
+      - { name: okf_concept,    from: "$.concept" }
+      - { name: okf_anchors,    from: "$.anchors_written" }
+
+  # ═══════════════ ACCEPTANCE — the ONE place the spec is read ═════════════════
+  # READ-ONLY and REPORT-ONLY: it never edits code, never edits the pass, and never
+  # stops the run. A gap means one of two documents is wrong, and which one is a human
+  # decision — the message names both routes.
+  - id: ctx_accept
+    action: build_context
+    vars:
+      story_id: "{{story}}"
+      exercises_csv: "{{exercises_csv}}"
+      constraints_csv: "{{constraints_csv}}"
+      files_csv: "{{files}}"
+    context:
+      - { path: "{{story_path}}" }    # the acceptance criteria
+      - { path: "{{spec_file}}" }     # the contract — the ONLY step in this workflow that reads it
+      - { path: "{{design_doc}}" }    # what was designed
+  - id: accept_check
+    action: agent_query
+    tools: Read                       # the generated files arrive as paths, not inlined
+    include_standards: false
+    schema: { ok: "<true|false>", gaps: "<one line per gap, or empty>" }
+    mock: { ok: "true", gaps: "" }
+    task: |
+      Story {{story_id}} was just implemented in the frontend lane. Judge ONLY this:
+      does the UI that now exists satisfy the requirements the story delivers, AS THE
+      SPEC WORDS THEM?
+
+      In scope: {{exercises_csv}} (delivered) and {{constraints_csv}} (must hold) — the
+      UX- ids among them are this lane's to realise. Resolve each id's wording from
+      spec.md in context; that wording, not the design's restatement of it, is what the
+      code is measured against.
+
+      Read the files this run wrote:
+          {{files_csv}}
+      plus anything they import that you need to follow. Do not modify a single file.
+
+      Report a gap ONLY where the UI fails to deliver an in-scope id as the spec words
+      it, or breaks an in-scope constraint. These are NOT gaps, and reporting them is
+      noise that hides the real ones:
+      - server-side behaviour — this lane cannot implement it and must not;
+      - a requirement no story has claimed yet, or one another story delivers;
+      - style, naming, structure or test-coverage opinions — other gates own those;
+      - anything the design pass deliberately deferred and named under its risks.
+
+      One line per gap: the id, what the spec requires, and what the UI does instead.
+      Set ok=false only when you found at least one. If the SPEC and the DESIGN disagree
+      about an in-scope id, that IS a gap — say which document you believe is wrong and
+      why, because the two routes out of it are different commands.
+    outputs:
+      - { name: accept_ok,   from: "$.ok" }
+      - { name: accept_gaps, from: "$.gaps" }
+  - id: accept_notice
+    condition: "{{accept_ok}} != true"
+    action: verify_context
+    require_value: accept_ok
+    equals: "true"
+    on_mismatch: continue
+    on_mismatch_message: |
+      ACCEPTANCE — story {{story}}'s UI does not yet satisfy the spec wording of the ids it delivers:
+
+      {{accept_gaps}}
+
+      Nothing was changed to fix this: the code follows UI design pass {{design_pass}}, so a gap
+      here means either the design was wrong or the spec has moved. Route by which it is —
+      the design is wrong: /appweaver story-plan {{story}} (a new pass supersedes this one);
+      the spec is wrong: /appweaver sync-spec (⌛ not yet built — until it is, fold the change back by hand under .appweaver/SPEC-EDIT-PROTOCOL.md), then sync-stories, then story-plan.
+      Run /appweaver build either way — a design that is right and code that does not compile
+      is a third thing, and build is where that one surfaces.
 
-  # 4. Post-execution hooks.
+  # 9. Post-execution hooks.
   - id: resolve_post_hooks
     action: execute_script
     script: { ref: actions }
@@ -258,10 +652,12 @@ workflow:
     hooks_from_variable: after_hooks
 
 outputs:
-  feature_dir: "{{feature_dir}}"
-  ui_design_doc: "{{ui_design_doc}}"
-  lane_id: "{{lane_id}}"
-  lane_source_path: "{{lane_source_path}}"
+  story: "{{story}}"
+  built_from: "{{design_doc}} — UI design pass {{design_pass}} (designed against spec {{design_spec_version}}; spec now {{current_version}})"
+  requirements: "{{exercises_csv}}"
   files: "{{files}}"
-  okf_concept: "{{okf_concept}}"
-  next: "/appweaver build  (generated the {{lane_id}} lane's UI under {{lane_source_path}} and merged the files into the feature's OKF concept at {{okf_concept}}; build compiles every declared lane, so a break in either one surfaces there)"
+  lane: "{{lane_id}} → {{lane_source_path}}"
+  okf_concept: "{{okf_concept}} (this run's files MERGED into ui_source_files; the service lane's source_files is untouched)"
+  acceptance: "ok={{accept_ok}} · gaps: {{accept_gaps}}"
+  stale_ids: "{{stale_csv}}"
+  next: "/appweaver build — it compiles every declared lane, so a break in either surfaces there. Then /appweaver analyze-slice. The story stays OPEN: /appweaver close-story — which would ratify its ADRs, flip its interface entries live and archive the passes — is ⌛ NOT BUILT YET, so there is no transition out of in-flight and no last gate before merge."