aw-spec-cli 0.1.26 → 0.1.28

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

@@ -28,7 +28,7 @@
 #
 # EACH LANE IS GATED ON ITS OWN, AND A LANE'S GAP IS NOT THE RUN'S. A declared lane needs
 # two things before it can generate: the plan for THIS run (its master plan, or this
-# change's delta plan) and a scaffolded project under the source path it declares. A lane
+# change's delta plan) and a scaffolded project under the lane root folder it declares. A lane
 # that is missing either is REPORTED with the fix named and SKIPPED — the other lane still
 # runs. Failing the whole command for the frontend's sake is how a backend that was ready
 # goes unbuilt; failing silently is how a frontend that was never generated reports green.
@@ -38,6 +38,12 @@
 # pipeline, so each runnable lane confirms first, naming its stack, its plan and the
 # subtree it will write into. Answering no to one lane leaves the other free to run.
 #
+# THE FRONTEND BINDS TO THE SERVICE AS BUILT. Between the two lanes, the service's API
+# document is exported from the running code, the frontend's client is generated from it,
+# and the operation ids the frontend plan cites are checked against it; the frontend then
+# generates with the document in context. Each of those steps warns rather than stops —
+# see the API CONTRACT block before the lane swap.
+#
 # THE PLAN SAYS WHAT TO BUILD, THE MODEL SAYS WHAT THE DOMAIN IS. This phase does NOT read
 # spec.md — analyze-plan already conformed the plans to it, so the plan is the complete,
 # authoritative source for WHICH elements exist, where each lives and what surface they
@@ -81,15 +87,15 @@
 # the constitution halves + this phase's rule sets. Each lane takes its rules from its own
 # heading of tech-rule-bindings, and the frontend set is loaded only when that lane runs,
 # so a backend-only project sees exactly the rules it did before:
-#   • BACKEND  — `## /aw-spec-implement` on the bootstrap path, `## /aw-spec-implement-delta`
-#     on the delta path. Keyed by MODE, which is what the two commands did separately, so
-#     no project's rule set changes by being merged into one command.
-#   • FRONTEND — `## /aw-spec-implement-ui`, both paths. There was never a delta heading
-#     for this lane because the delta half of it was never built; it is built here.
+#   • BACKEND  — `## /aw-spec-implement-backend`, both paths.
+#   • FRONTEND — `## /aw-spec-implement-frontend`, both paths.
+#   A change's code is generated against the same rules as the master it changes, so
+#   neither lane has a separate delta heading.
 #
-# TWO PATHS PER LANE. Each lane owns the source path stacks.json declares for it and the
-# test path lane-verify resolves beside it — `tests/` next to a .NET `src/`, the source
-# path itself for a stack that keeps its tests inside — and writes nothing outside them.
+# TWO PATHS PER LANE. Each lane owns the lane root folder stacks.json declares for it and the
+# test path lane-verify resolves for it — `backend/tests/` inside a new lane root folder,
+# `tests/` next to a classic .NET `src/`, the lane root folder itself for a stack that keeps
+# its tests inside — and writes nothing outside them.
 # The one exception is registering a test project the lane had to create, in whatever
 # file the lane's test command discovers tests through (a .NET solution file). A file
 # written elsewhere belongs to the other lane or to no lane at all, and the project gate
@@ -99,35 +105,35 @@
 #
 # A FILE LIST IS NOT A FINISHED LANE. Each generating lane is handed its plan's element
 # list and reports every element back as done or blocked; `plan-coverage` then checks the
-# code under the lane's source path for every identifier the plan introduces. Whatever
+# code under the lane root folder for every identifier the plan introduces. Whatever
 # either check leaves open gets one completion pass, and anything still open after it
 # stops the run once both lanes have generated — so a pass that stopped at five use-cases
 # of seven is reported, not shipped.
 #
 # A LANE'S GAP DISABLES THAT LANE, NOT THE RUN. Three things a lane needs are checked per
-# lane and reported per lane: its source path is on disk, its plan is there, and a project
+# lane and reported per lane: its lane root folder is on disk, its plan is there, and a project
 # is scaffolded under it. Any of them missing skips that lane with the command that fixes
 # it named, and every other declared lane still generates; only when NOTHING can run does
 # the run stop, with all the reasons printed. The whole-run stop is reserved for states
 # with no correct lane to fall back on — no lane declared at all, a lane declaring no
-# source path, and two lanes claiming overlapping subtrees.
+# lane root folder, and two lanes claiming overlapping subtrees.
 #
 # WHAT IT DOES NOT DO. It never writes spec.md, a master plan or the domain model, and it
 # never closes a change — finalize-delta merges the change's spec and model halves,
 # analyze-slice verifies the slice, and close-delta archives it and bumps the version.
 #
 # Prereqs: /appweaver plan (+ analyze-plan, or analyze-plan-delta for a change), and a
-# project scaffolded under each lane's source path — this phase GENERATES into that tree,
-# so with no project there is nowhere to place the files. /appweaver foundation unpacks one
-# where a bundle ships for the stack; a stack with no bundle scaffolds with its own tooling
-# instead, and the gate accepts either, since it tests for a project rather than a bundle.
+# project scaffolded under each lane root folder — this phase GENERATES into that tree,
+# so with no project there is nowhere to place the files. /appweaver foundation scaffolds one,
+# from a pack or from a spec; a team may also scaffold with the stack's own tooling, and the
+# gate accepts any of them, since it tests for a project rather than for how it got there.
 #
 # Launch:  /appweaver implement [guidance]
 #          /appweaver implement CR-20260910-…   (implement THAT open change, no prompt)
 # =============================================================================
 
 name: aw-spec-implement
-description: "Generate the aggregate's source files and paired tests from its lane plans — the backend lane from backend-plan.md when a backend stack is declared, the frontend lane from frontend-plan.md when a frontend stack is, both when both are. One command covers backend-only, frontend-only and full-stack projects and absorbs the former implement-ui and implement-delta. Self-detecting off the changes on disk — with none open it generates from the master plans; with one or more open it ASKS which change and generates only what that change's delta plans mark ADDED or MODIFIED, leaving the masters untouched. Every lane is gated on its own source path, its own plan and its own scaffolded project, and a lane missing any of them is reported and skipped rather than failing the other lane; each runnable lane confirms before it writes. Model-driven, and it does not read the spec — analyze-plan already conformed the plans to it. The plan says WHAT to build; the bounded context's domain-model.md, in context alongside it, says what the domain IS — the entity names, the boundary and the text of every invariant the plan cites by id — joined on the delta path by that change's own model delta, since the master is not merged until finalize-delta. The stack binds here from the lane declaration and the constitution halves; the plans stay technology-agnostic."
+description: "Generate the aggregate's source files and paired tests from its lane plans — the backend lane from backend-plan.md when a backend stack is declared, the frontend lane from frontend-plan.md when a frontend stack is, both when both are. One command covers backend-only, frontend-only and full-stack projects and absorbs the former implement-ui and implement-delta. Self-detecting off the changes on disk — with none open it generates from the master plans; with one or more open it ASKS which change and generates only what that change's delta plans mark ADDED or MODIFIED, leaving the masters untouched. Every lane is gated on its own lane root folder, its own plan and its own scaffolded project, and a lane missing any of them is reported and skipped rather than failing the other lane; each runnable lane confirms before it writes. Model-driven, and it does not read the spec — analyze-plan already conformed the plans to it. The plan says WHAT to build; the bounded context's domain-model.md, in context alongside it, says what the domain IS — the entity names, the boundary and the text of every invariant the plan cites by id — joined on the delta path by that change's own model delta, since the master is not merged until finalize-delta. The stack binds here from the lane declaration and the constitution halves; the plans stay technology-agnostic."
 version: 3.10.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
@@ -148,7 +154,7 @@ scripts:
 
 # Sticky standards seed = the UNIVERSAL always-on rule only (ai-rules). Each lane's
 # FRAMEWORK / code-generation rule files are CONFIGURATION, loaded per-lane from
-# guardrails/projects/<project>/tech-rule-bindings.md by the tech-select module (see the
+# guardrails/<project>/tech-rule-bindings.md by the tech-select module (see the
 # tech_select steps below). Per the rule-partition this phase loads NO domain rule file —
 # everything domain reached the code through spec → plan. The architecture and UX bases
 # arrive via constitution.technical.md / constitution.ui.md (referred to directly, as-is —
@@ -247,15 +253,37 @@ vars:
   fe_completion_ran: "false"
   fe_gap_names: ""
   fe_gaps_text: "none"
+  # THE API CONTRACT between the lanes — see the block before the lane swap. Every flag
+  # starts lowered, so a run without a frontend lane never touches any of it.
+  contract_go: "false"
+  contract_ok: ""
+  contract_doc: ""
+  contract_doc_exists: "false"
+  contract_reason: ""
+  contract_already: "false"
+  contract_fresh: "true"
+  contract_log: ""
+  contract_placeholder: ""
+  contract_export_status: ""
+  contract_status: "not exported — no API document is in context, so take each binding from the plan alone and say so in your summary"
+  client_go: "false"
+  client_ask: "false"
+  client_answer: ""
+  client_saved: "false"
+  client_run: "false"
+  client_present: "false"
+  client_ok: ""
+  client_cmd: ""
+  client_log: ""
+  client_status: "none was generated — write the calls in the lane's client layer from the API document, exactly as it states them"
+  check_ok: ""
+  check_reason: ""
   lanes_complete: "true"
   generate_any: "false"
   record_edges: "false"
   overview_ok: "false"
   domain_model: ""
   domain_model_exists: "false"
-  # The backend lane's rule-set heading, keyed by MODE — see the header. The frontend
-  # lane's is the same on both paths, so it is written inline at its include.
-  be_tech_command: "aw-spec-implement"
   # HOOK PHASES. The merged command fires the phase of every branch it actually takes, so
   # an extensions.yml wired to any of the three former commands keeps working:
   # before/after_implement always, the _ui pair when the frontend lane generates, the _cr
@@ -272,15 +300,15 @@ workflow:
   #    kind: a backend-only and a frontend-only project are both correct states, and which
   #    lanes exist is exactly what it is here to find out.
   #
-  #    --allow-missing-root, because a lane whose source path is not on disk is THAT LANE'S
+  #    --allow-missing-root, because a lane whose lane root folder is not on disk is THAT LANE'S
   #    gap, not the run's. This phase is per-lane throughout — a missing plan or a missing
   #    project is reported at step 5 and the other lane still generates — and a missing root
   #    is the same kind of gap, most often a declared frontend that `foundation` has not
-  #    unpacked yet. With the check left on it arrives here instead, as a whole-run stop
+  #    scaffolded yet. With the check left on it arrives here instead, as a whole-run stop
   #    that takes the ready lane down with it. It is re-checked per lane at step 5 from
   #    `*_root_exists`, which lane-verify reports whether or not the on-disk half is armed.
   #
-  #    What still stops the run: no lane declared at all, a lane declaring no source path,
+  #    What still stops the run: no lane declared at all, a lane declaring no lane root folder,
   #    and two lanes claiming overlapping subtrees. Those are declaration errors with no
   #    correct lane to fall back to, and none of them is a state any phase can work around.
   - id: lane_verify
@@ -316,6 +344,8 @@ workflow:
       - { name: fe_build,       from: "$.frontend_build" }
       - { name: fe_test,        from: "$.frontend_test" }
       - { name: fe_reserved,    from: "$.frontend_reserved_csv" }
+      - { name: fe_workdir,     from: "$.frontend_workdir" }
+      - { name: fe_client,      from: "$.frontend_client" }
 
   - id: require_lanes
     action: verify_context
@@ -401,7 +431,6 @@ workflow:
       mode: "delta"
       pre_cr_phase: "before_implement_cr"
       post_cr_phase: "after_implement_cr"
-      be_tech_command: "aw-spec-implement-delta"
 
   - id: pick_change
     condition: "{{mode}} == delta"
@@ -539,8 +568,8 @@ workflow:
   #    detect-project searches the LANE'S OWN subtree for an ecosystem manifest (.sln/
   #    .csproj, pom.xml, build.gradle, package.json, go.mod, Cargo.toml, pyproject.toml),
   #    falls back to the whole repo, and reports which scope answered. How the project got
-  #    there is not asked — `foundation` unpacked it, or the team scaffolded it with the
-  #    stack's own tooling.
+  #    there is not asked — `foundation` unpacked or built it, or the team scaffolded it with
+  #    the stack's own tooling.
   - id: be_detect_project
     condition: "{{be_declared}} == true"
     action: execute_script
@@ -555,7 +584,7 @@ workflow:
   # in a two-lane project is the service lane's manifest, and generating this lane's code
   # against it is exactly the failure the lane model exists to prevent — a frontend that
   # was never scaffolded, generated into anyway, reporting green. The service lane accepts
-  # either scope, because the layout that keeps a manifest beside the lane root rather than
+  # either scope, because the layout that keeps a manifest beside the lane root folder rather than
   # inside it is a normal one for it.
   - id: fe_detect_project
     condition: "{{fe_declared}} == true"
@@ -586,13 +615,13 @@ workflow:
     action: verify_context
     require_true: be_root_exists
     on_false: continue
-    on_false_message: "BACKEND LANE SKIPPED — lane `{{be_lane_id}}` ({{be_title}}) declares source path `{{be_source_path}}` in .appweaver/stacks.json, and that path is not a directory in this repository. A lane owns its subtree and this phase writes into it, so there is nothing to generate into: unpack a project there with /appweaver foundation <FoundationName> <AppName> where a bundle ships for {{be_profile}}, create one with the stack's own tooling, or re-run /appweaver select-stack and point the lane at the directory that really holds its source. Nothing is generated for this lane; any other declared lane still runs."
+    on_false_message: "BACKEND LANE SKIPPED — lane `{{be_lane_id}}` ({{be_title}}) declares lane root folder `{{be_source_path}}` in .appweaver/stacks.json, and that path is not a directory in this repository. A lane owns its subtree and this phase writes into it, so there is nothing to generate into: scaffold a project there with /appweaver foundation (a pack or a spec for {{be_profile}}, or a spec you give it), create one with the stack's own tooling, or re-run /appweaver select-stack and point the lane at the directory that really holds its source. Nothing is generated for this lane; any other declared lane still runs."
   - id: warn_be_project
     condition: "{{be_declared}} == true"
     action: verify_context
     require_true: be_project_ok
     on_false: continue
-    on_false_message: "BACKEND LANE SKIPPED — no project found under the {{be_lane_id}} lane's source path `{{be_source_path}}`, nor anywhere else in this repository. This phase GENERATES into an existing project tree, so one has to be scaffolded first: run /appweaver foundation <FoundationName> <AppName> where a foundation bundle ships for {{be_profile}}, or create the project with the stack's own tooling under that path. Any ecosystem manifest marks it — .sln/.csproj, pom.xml, build.gradle(.kts), package.json, go.mod, Cargo.toml or pyproject.toml."
+    on_false_message: "BACKEND LANE SKIPPED — no project found under the {{be_lane_id}} lane root folder `{{be_source_path}}`, nor anywhere else in this repository. This phase GENERATES into an existing project tree, so one has to be scaffolded first: run /appweaver foundation, which scaffolds it from a pack or from a spec (one it ships for {{be_profile}}, or one you give it), or create the project with the stack's own tooling under that path. Any ecosystem manifest marks it — .sln/.csproj, pom.xml, build.gradle(.kts), package.json, go.mod, Cargo.toml or pyproject.toml."
   - id: warn_fe_plan
     condition: "{{fe_declared}} == true"
     action: verify_context
@@ -604,15 +633,15 @@ workflow:
     action: verify_context
     require_true: fe_root_exists
     on_false: continue
-    on_false_message: "FRONTEND LANE SKIPPED — lane `{{fe_lane_id}}` ({{fe_title}}) declares source path `{{fe_source_path}}` in .appweaver/stacks.json, and that path is not a directory in this repository. A lane owns its subtree and this phase writes into it, so there is nothing to generate into: unpack a project there with /appweaver foundation <FoundationName> <AppName> where a bundle ships for {{fe_profile}}, create one with the stack's own tooling, or re-run /appweaver select-stack and point the lane at the directory that really holds its source. Nothing is generated for this lane; any other declared lane still runs."
+    on_false_message: "FRONTEND LANE SKIPPED — lane `{{fe_lane_id}}` ({{fe_title}}) declares lane root folder `{{fe_source_path}}` in .appweaver/stacks.json, and that path is not a directory in this repository. A lane owns its subtree and this phase writes into it, so there is nothing to generate into: scaffold a project there with /appweaver foundation (a pack or a spec for {{fe_profile}}, or a spec you give it), create one with the stack's own tooling, or re-run /appweaver select-stack and point the lane at the directory that really holds its source. Nothing is generated for this lane; any other declared lane still runs."
   - id: warn_fe_project
     condition: "{{fe_declared}} == true"
     action: verify_context
     require_true: fe_project_ok
     on_false: continue
-    on_false_message: "FRONTEND LANE SKIPPED — no frontend project found under the {{fe_lane_id}} lane's source path `{{fe_source_path}}`. detect-project searched that subtree and then the whole repository, and answered at scope `{{fe_project_scope}}`; `lane` is the only scope this lane accepts. Scaffold a project there — /appweaver foundation <FoundationName> <AppName> where a bundle ships for {{fe_profile}}, or the stack's own tooling — and re-run implement. 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_false_message: "FRONTEND LANE SKIPPED — no frontend project found under the {{fe_lane_id}} lane root folder `{{fe_source_path}}`. detect-project searched that subtree and then the whole repository, and answered at scope `{{fe_project_scope}}`; `lane` is the only scope this lane accepts. Scaffold a project there — /appweaver foundation, from a pack or a spec for {{fe_profile}} or a spec you give it, or the stack's own tooling — and re-run implement. 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."
 
-  # 6. RUNNABLE = declared AND its source path is on disk AND its plan is there AND its
+  # 6. RUNNABLE = declared AND its lane root folder is on disk AND its plan is there AND its
   #    project is there, as one ordered assignment plus a knockdown per condition, since
   #    the engine has no compound conditions. An undeclared lane stays false either way —
   #    its `declared` value is what the raise assigns.
@@ -676,7 +705,7 @@ workflow:
     action: verify_context
     require_true: generate_any
     on_false: stop
-    on_false_message: "Nothing to implement — no declared lane is both ready and confirmed. Either every declared lane was skipped for a reason printed above (its source path, its plan or its project is missing), or each one that was ready was declined at the prompt. Backend lane declared {{be_declared}}, ready {{be_runnable}}; frontend lane declared {{fe_declared}}, ready {{fe_runnable}}. Fix the reasons named above, or re-run and confirm a lane."
+    on_false_message: "Nothing to implement — no declared lane is both ready and confirmed. Either every declared lane was skipped for a reason printed above (its lane root folder, its plan or its project is missing), or each one that was ready was declined at the prompt. Backend lane declared {{be_declared}}, ready {{be_runnable}}; frontend lane declared {{fe_declared}}, ready {{fe_runnable}}. Fix the reasons named above, or re-run and confirm a lane."
 
   # 8. EACH GENERATING LANE'S authoring MODE — the run's mode where the lane is going, and
   #    `skip` where it is not, which silences both of that lane's branches without a
@@ -754,15 +783,15 @@ workflow:
       - { name: fe_existing_count, from: "$.count" }
 
   # 9. Each generating lane's code-generation rule files → sticky standards (configuration,
-  #    not hardcoded). Loaded only for a lane that is actually going to generate, and the
-  #    backend's heading is keyed by mode (see the header). No blocking gate: an
+  #    not hardcoded). Loaded only for a lane that is actually going to generate, under
+  #    the same heading on both paths (see the header). No blocking gate: an
   #    unconfigured project soft-continues, since the constitution halves still carry each
   #    lane's ratified base.
   #
   #    EACH LANE'S RULES ARE LOADED BESIDE ITS OWN STEPS, AND THE SECOND LANE REPLACES
   #    THE FIRST'S. Both includes used to run here, before either lane generated — and
   #    sticky standards only accumulate, so on a full-stack run the backend generator was
-  #    shown `## /aw-spec-implement-ui` and the frontend generator the service set. Each
+  #    shown `## /aw-spec-implement-frontend` and the frontend generator the service set. Each
   #    prompt says which lane it is in, but it said so inside an envelope that contradicted
   #    it, and the envelope is the part the model cannot argue with. The frontend include
   #    now sits immediately before the FRONTEND sections below and passes replace, which
@@ -771,7 +800,7 @@ workflow:
     condition: "{{be_go}} == true"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: "{{be_tech_command}}" }
+    with: { command: aw-spec-implement-backend }
 
   # 10. Pre-execution hooks — see the hook-phase vars above.
   - id: resolve_pre_hooks
@@ -891,6 +920,11 @@ workflow:
         Cross-Cutting Concerns table (audit / retention / data-exposure — the CN-/DC-
         realisations); and each integration contract (IC-) in the External Integrations
         table. Implement every port the plan declares.
+      - GIVE EVERY ENDPOINT ITS OPERATION ID. Where the plan names an endpoint's
+        **Operation id**, set it as this stack's published API document names operations
+        (its OpenAPI operationId), spelled exactly as the plan writes it. The frontend lane
+        finds the endpoint by that id in the document exported from this code, so an
+        endpoint left on a framework-generated name is one it cannot find.
       - Author a paired test for every plan behaviour / use-case / endpoint; derive the
         cases from the plan's pre/post/invariant contracts and cite the spec id (FR / BR /
         CN / DC / IC / US) from its Traceability section. Include tests for the constraints
@@ -1041,6 +1075,10 @@ workflow:
         invariant, handler orchestration, API error contract, the Cross-Cutting Concerns
         realisations (audit / retention / data-exposure — CN-/DC-) and the External
         Integrations table's contracts (IC-) exactly as the delta plan states.
+      - GIVE EVERY ENDPOINT THIS CHANGE ADDS OR CHANGES the operation id the delta plan
+        names, set as this stack's published API document names operations (its OpenAPI
+        operationId) and spelled exactly; an existing endpoint keeps the id it has. The
+        frontend lane finds each endpoint by that id in the exported document.
       - COMPONENTS: if a delta element depends on a framework component, code against its
         ABSTRACTION / port as the delta plan declares — do NOT hand-roll it. Installing the
         component (packages, wiring, config) is /appweaver add-component <Component>; if
@@ -1140,7 +1178,8 @@ workflow:
         under a different name is renamed to the plan's name, with its references — the
         plan's names are the ubiquitous language.
       - An element the plan names by intent (a port, an adapter, an endpoint route) is done
-        when the code realises it, whatever the framework calls it; report it `done`.
+        when the code realises it, whatever the framework calls it; report it `done`. An
+        endpoint still carries the operation id the plan names, set exactly.
       - If an element cannot be realised, do not work around it: report it `blocked` and
         say what stops you. A plan that is wrong is fixed in plan / analyze-plan.
       - Report every listed element in an `elements` list in your closing JSON block:
@@ -1165,7 +1204,7 @@ workflow:
   # recorded). Without the union a backend run would erase the frontend lane's source_files
   # and vice-versa, and either lane may have run first. ⌛ The trade-off is that a file this
   # lane DELETED stays listed until something prunes it; a lane-scoped replace needs
-  # concept-upsert to learn about lane roots, which is a script change and not built.
+  # concept-upsert to learn about lane root folders, which is a script change and not built.
   - id: xref_concept_backend
     condition: "{{be_go}} == true"
     action: execute_script
@@ -1185,13 +1224,156 @@ workflow:
     outputs:
       - { name: okf_concept, from: "$.concept" }
 
+  # ══════════════ THE API CONTRACT — the built service, as the frontend sees it ═══
+  # The frontend binds to the service through its published API document, and the document
+  # that counts is the one the CODE serves: routes, verbs, parameters, field names and
+  # status codes as built, which the plans only describe. So before the frontend lane
+  # generates, three steps, each of which WARNS and carries on — the frontend still
+  # generates, from its plan, when one of them cannot run:
+  #   1. EXPORT — start the service with its lane's `contract_run`, save what it serves at
+  #      `contract` under its lane root folder, stop it (contract-export). The two values
+  #      come from the lane in stacks.json — where foundation records a pack's own — or
+  #      else from the stack profile.
+  #   2. CLIENT — run the frontend lane's `client` command, which generates the client from
+  #      that document. A lane with none yet asks the developer once and records the
+  #      answer on the lane; an empty answer carries on without a generated client.
+  #   3. CHECK — every operation id the frontend plan cites must be in the document
+  #      (contract-check, by script).
+  # It runs whenever the frontend lane does, including when the service was built in an
+  # earlier run, and only where a service lane is declared.
+  - id: contract_arm
+    condition: "{{fe_go}} == true"
+    action: set
+    vars: { contract_go: "{{be_declared}}" }
+  - id: contract_export
+    condition: "{{contract_go}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: contract-export
+    outputs:
+      - { name: contract_ok,          from: "$.ok" }
+      - { name: contract_doc,         from: "$.doc" }
+      - { name: contract_doc_exists,  from: "$.doc_exists" }
+      - { name: contract_reason,      from: "$.reason" }
+      - { name: contract_already,     from: "$.already_running" }
+      - { name: contract_ops,         from: "$.operations" }
+      - { name: contract_log,         from: "$.log_tail" }
+      - { name: contract_placeholder, from: "$.placeholder" }
+      - { name: contract_export_status, from: "$.status" }
+  - id: warn_contract_export
+    condition: "{{contract_go}} == true"
+    action: verify_context
+    require_true: contract_ok
+    on_false: continue
+    on_false_message: "API DOCUMENT NOT EXPORTED — {{contract_reason}}. The service lane `{{be_lane_id}}` is started with its `contract_run` command and its document fetched from its `contract` URL, both read from .appweaver/stacks.json or else its stack profile; correct them on the lane there if they do not fit this project, start anything the service needs, and re-run implement. Until then the frontend lane binds from its plan alone. Service output: {{contract_log}}"
+  - id: contract_stale_flag
+    condition: "{{contract_already}} == true"
+    action: set
+    vars: { contract_fresh: "false" }
+  - id: warn_contract_stale
+    condition: "{{contract_go}} == true"
+    action: verify_context
+    require_true: contract_fresh
+    on_false: continue
+    on_false_message: "WARNING — the API document was {{contract_reason}}. Stop that service and re-run implement to export the code as it is now."
+  - id: contract_status_set
+    condition: "{{contract_doc_exists}} == true"
+    action: set
+    vars: { contract_status: "{{contract_export_status}}; it is in context" }
+
+  # 2. THE CLIENT, generated from the document — so only once there is one.
+  - id: client_arm
+    condition: "{{contract_doc_exists}} == true"
+    action: set
+    vars: { client_go: "{{fe_go}}" }
+  - id: client_ask_arm
+    condition: "{{fe_client}} == "
+    action: set
+    vars: { client_ask: "{{client_go}}" }
+  - id: ask_client
+    condition: "{{client_ask}} == true"
+    action: ask
+    prompt: |
+      The frontend lane `{{fe_lane_id}}` ({{fe_title}}) has no `client` command, so its API
+      client cannot be generated from the service's document ({{contract_doc}}).
+      Type the command that generates it. It runs in `{{fe_workdir}}`, and
+      {{contract_placeholder}} in it stands for the document's path — for example:
+        npx openapi-typescript {{contract_placeholder}} -o lib/api/schema.d.ts
+      It is saved on the lane in .appweaver/stacks.json and used on every run after this one.
+      Leave it empty to carry on without a generated client.
+    answer_var: client_answer
+  - id: client_save
+    condition: "{{client_ask}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-set
+    args: ["--id", "{{fe_lane_id}}", "--set", "client={{client_answer}}"]
+    outputs:
+      - { name: client_saved, from: "$.written" }
+  - id: client_saved_set
+    condition: "{{client_saved}} == true"
+    action: set
+    vars: { fe_client: "{{client_answer}}" }
+  - id: client_run_arm
+    condition: "{{fe_client}} != "
+    action: set
+    vars: { client_run: "{{client_go}}" }
+  - id: contract_client
+    condition: "{{client_run}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: contract-client
+    outputs:
+      - { name: client_ok,  from: "$.ok" }
+      - { name: client_cmd, from: "$.cmd" }
+      - { name: client_log, from: "$.failing_excerpt" }
+  - id: warn_client_failed
+    condition: "{{client_run}} == true"
+    action: verify_context
+    require_true: client_ok
+    on_false: continue
+    on_false_message: "API CLIENT NOT GENERATED — the frontend lane's `client` command failed: {{client_log}}. Correct `client` on the `{{fe_lane_id}}` lane in .appweaver/stacks.json and re-run implement. Until then the frontend lane writes its calls from the API document."
+  - id: client_status_set
+    condition: "{{client_ok}} == true"
+    action: set
+    vars:
+      client_present: "true"
+      client_status: "generated just now by `{{client_cmd}}` from the API document — call the service THROUGH it, and never edit a generated file"
+  - id: warn_no_client
+    condition: "{{client_go}} == true"
+    action: verify_context
+    require_true: client_present
+    on_false: continue
+    on_false_message: "NO API CLIENT GENERATED — the frontend lane `{{fe_lane_id}}` has no working `client` command, so this run writes its calls from the API document {{contract_doc}} instead. Set `client` on the lane in .appweaver/stacks.json (`{{contract_placeholder}}` stands for the document) to generate the client on the next run."
+
+  # 3. THE CHECK — the operation ids the frontend plan cites, against the document.
+  - id: contract_check
+    condition: "{{contract_doc_exists}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: contract-check
+    args: ["--plan", "{{fe_plan}}", "--doc", "{{contract_doc}}"]
+    outputs:
+      - { name: check_ok,     from: "$.ok" }
+      - { name: check_reason, from: "$.reason" }
+  - id: warn_contract_check
+    condition: "{{contract_doc_exists}} == true"
+    action: verify_context
+    require_true: check_ok
+    on_false: continue
+    on_false_message: "CONTRACT CHECK — {{check_reason}}. Each binding in {{fe_plan}} names the endpoint it calls by the operation id the backend plan gives it, and the built service must serve that id. Either the plan cites the wrong id (fix it with /appweaver plan, then analyze-plan) or the service never gave the endpoint that id (re-run implement for the backend lane). The frontend lane still generates; these bindings are where a call will fail."
+
   # ══════════════ THE LANE SWAP — the frontend's rules replace the backend's ═══
   # build_context already scoped the two lanes' PAYLOADS apart; this is the same boundary
   # for their STANDARDS, which the envelope carries and which nothing used to reset. It
   # runs here rather than up with the backend's include because standards accumulate:
   # loading both before either lane generated is precisely what showed each generator the
   # other lane's rule set. `replace` resets to the declared seed (ai-rules stays) and then
-  # loads `## /aw-spec-implement-ui`, so from here down the envelope is the frontend's.
+  # loads `## /aw-spec-implement-frontend`, so from here down the envelope is the frontend's.
   #
   # Nothing after the frontend sections regenerates backend code — the OKF steps that
   # follow run include_standards: false — so the swap needs no undo.
@@ -1199,12 +1381,13 @@ workflow:
     condition: "{{fe_go}} == true"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-implement-ui, replace: "true" }
+    with: { command: aw-spec-implement-frontend, replace: "true" }
 
   # ═══════════ FRONTEND LANE — bootstrap, generate from the MASTER plan ════════
   # The experience twin of the service generation, one lane over. Its own build_context,
   # because the envelope persists across steps and the two lanes must not see each other's
   # payload — the frontend binds to the service's PUBLISHED surface, never its internals.
+  # That surface is the API document the contract block exported, when there is one.
   - id: ctx_frontend
     condition: "{{fe_mode}} == bootstrap"
     action: build_context
@@ -1212,6 +1395,7 @@ workflow:
       - { path: "{{fe_plan}}" }
       - { path: "{{domain_model}}", optional: true }   # the UBIQUITOUS LANGUAGE this lane's labels, states and messages use — and what a cited BR-nnn requires
       - { path: .appweaver/memory/constitution.ui.md, optional: true }   # the lane's ratified UX-* base — conventions, forbidden patterns, gates
+      - { path: "{{contract_doc}}", optional: true }   # the service's API document as BUILT — what every §5 binding calls
   - id: gen_frontend
     condition: "{{fe_mode}} == bootstrap"
     action: agent_generate
@@ -1305,6 +1489,17 @@ workflow:
           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.
+      - THE SERVICE'S API DOCUMENT IS THE CONTRACT. API document: {{contract_status}}.
+        Each §5 row names its endpoint by Operation id; find that operation in the
+        document and take EVERYTHING about the call from it — route, verb, path and query
+        parameters, request and response field names and their casing, status codes and
+        error codes. Never take a route, a field name or a paging convention from memory,
+        from convention or from the loaded standards' examples: the document is what the
+        built service actually answers. A §5 row whose id the document does not have is a
+        broken binding — realise the screen, leave that call unbound, report the element
+        `blocked` naming the id, and never guess a substitute.
+      - THE CLIENT: {{client_status}}. The client lives in this lane's client layer; a
+        generated client is called, never edited.
       - 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.
@@ -1346,6 +1541,7 @@ workflow:
       - { path: "{{frontend_plan}}", optional: true } # the master plan — READ ONLY, never amended here
       - { path: "{{domain_model}}", optional: true }  # the master model — the ubiquitous language as it stands BEFORE this change
       - { path: .appweaver/memory/constitution.ui.md, optional: true }
+      - { path: "{{contract_doc}}", optional: true }  # the service's API document as BUILT — what every binding row calls
   - id: gen_frontend_delta
     condition: "{{fe_mode}} == delta"
     action: agent_generate
@@ -1425,6 +1621,15 @@ workflow:
         service delta's "Contract deltas for the frontend lane" table as the delta plan
         cites them. Generate no server-side behaviour, no persistence and no business rule
         evaluation.
+      - THE SERVICE'S API DOCUMENT IS THE CONTRACT. API document: {{contract_status}}.
+        Each binding row leads with its endpoint's operation id; find that operation in
+        the document and take EVERYTHING about the call from it — route, verb, path and
+        query parameters, request and response field names and their casing, status
+        codes and error codes — never from memory, convention or the standards' examples.
+        A binding whose id the document does not have is broken: leave that call unbound,
+        report the element `blocked` naming the id, and never guess a substitute.
+      - THE CLIENT: {{client_status}}. The client lives in this lane's client layer; a
+        generated client is called, never edited.
       - Author a paired test for every ADDED/MODIFIED screen, interaction and state,
         including the unwanted-behaviour states and an accessibility assertion per
         interactive surface, citing the requirement id THE DELTA PLAN NAMES for that row
@@ -1499,6 +1704,10 @@ workflow:
         plan's names are the ubiquitous language.
       - A screen or a binding is done when the code realises it, whatever its route or
         file is called; report it `done`.
+      - A binding calls the operation its id names in the service's API document
+        ({{contract_status}}), taking route, verb, parameters, field names and status codes
+        from there, through the client ({{client_status}}). An id the document does not
+        have stays `blocked`; never guess a substitute.
       - If an element cannot be realised, do not work around it: report it `blocked` and
         say what stops you. A plan that is wrong is fixed in plan / analyze-plan.
       - Report every listed element in an `elements` list in your closing JSON block:
@@ -1554,7 +1763,7 @@ workflow:
     action: verify_context
     require_true: lanes_complete
     on_false: stop
-    on_false_message: "PARTIAL GENERATION — implement did not realise every plan element, even after one completion pass. Backend lane: {{be_gaps_text}}. Frontend lane: {{fe_gaps_text}}. Everything written so far is kept and recorded in the OKF concept. An element reported `blocked` names what stops it — a plan that is wrong is fixed with /appweaver plan (then analyze-plan or analyze-plan-delta). An element with no code under the lane's source path is still to be written, or was written under a name that is not the plan's: re-run /appweaver implement to finish, which extends existing files rather than regenerating them."
+    on_false_message: "PARTIAL GENERATION — implement did not realise every plan element, even after one completion pass. Backend lane: {{be_gaps_text}}. Frontend lane: {{fe_gaps_text}}. Everything written so far is kept and recorded in the OKF concept. An element reported `blocked` names what stops it — a plan that is wrong is fixed with /appweaver plan (then analyze-plan or analyze-plan-delta). An element with no code under the lane root folder is still to be written, or was written under a name that is not the plan's: re-run /appweaver implement to finish, which extends existing files rather than regenerating them."
 
   # 11. CROSS-SLICE EDGES — a Cross-References row written into every SIBLING aggregate
   #     this one uses, read off the master backend plan (§1 References-by-id + its External
@@ -1691,5 +1900,5 @@ outputs:
   plan_gate_at: "{{gate_at}}"
   plan_gate_verdict: "{{gate_verdict}}"
   plan_gate_routed_to_specify: "{{gate_routed_csv}}"   # open spec/model gaps this code does not cover
-  note: "Lanes come from .appweaver/stacks.json — backend declared {{be_declared}} (ready {{be_runnable}}, implemented {{be_go}}), frontend declared {{fe_declared}} (ready {{fe_runnable}}, implemented {{fe_go}}). A declared lane that was skipped printed its reason above and did not stop the other one; an undeclared lane produces nothing and that is not a failure. Each generating lane read its PLAN for what to build and {{domain_model}} for what the domain is — plus {{delta_model}} on the delta path, since the master model does not carry the change until finalize-delta merges it. Every one of those documents was READ and none was written: this phase generates code and nothing else. Each lane's outcome is backend={{be_outcome}}, frontend={{fe_outcome}} — `already-implemented` means the lane wrote no files because every plan element was already realised in its source path, which is the correct result of re-running implement on a finished feature and not a failure. On the bootstrap path the plans were checked against analyze-plan's receipt before anything generated (tracked={{gate_tracked}}, fresh={{gate_fresh}}, gated {{gate_at}}) — tracked=false means this feature has never passed analyze-plan since the gate began recording what it proved, which is an unknown rather than a stale plan and blocks nothing; run /appweaver analyze-plan once to start the record."
+  note: "Lanes come from .appweaver/stacks.json — backend declared {{be_declared}} (ready {{be_runnable}}, implemented {{be_go}}), frontend declared {{fe_declared}} (ready {{fe_runnable}}, implemented {{fe_go}}). A declared lane that was skipped printed its reason above and did not stop the other one; an undeclared lane produces nothing and that is not a failure. Each generating lane read its PLAN for what to build and {{domain_model}} for what the domain is — plus {{delta_model}} on the delta path, since the master model does not carry the change until finalize-delta merges it. Every one of those documents was READ and none was written: this phase generates code and nothing else. Each lane's outcome is backend={{be_outcome}}, frontend={{fe_outcome}} — `already-implemented` means the lane wrote no files because every plan element was already realised in its lane root folder, which is the correct result of re-running implement on a finished feature and not a failure. On the bootstrap path the plans were checked against analyze-plan's receipt before anything generated (tracked={{gate_tracked}}, fresh={{gate_fresh}}, gated {{gate_at}}) — tracked=false means this feature has never passed analyze-plan since the gate began recording what it proved, which is an unknown rather than a stale plan and blocks nothing; run /appweaver analyze-plan once to start the record."
   next: "This run was mode `{{mode}}`, change `{{active_change}}` (empty on the bootstrap path). BOOTSTRAP → /appweaver build → analyze-slice → run. DELTA → /appweaver build → analyze-slice-delta {{active_change}} → finalize-delta → analyze-slice → close-delta, with the change still OPEN throughout — compile first, then analyze-slice-delta verifies that every element the delta plans marked ADDED or MODIFIED is actually in the code with a paired test (the gate that catches a lane you declined at the prompt above), then finalize-delta merges it into spec.md + the context's domain-model.md while leaving it open, analyze-slice verifies the slice against those merged masters while a red result is still recoverable, and close-delta LAST archives the change and bumps the version."