aw-spec-cli 0.1.27 → 0.1.29

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

@@ -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,11 +87,10 @@
 # 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 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,
@@ -248,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
@@ -317,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
@@ -402,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"
@@ -755,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
@@ -772,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
@@ -892,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
@@ -1042,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
@@ -1141,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:
@@ -1186,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.
@@ -1200,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
@@ -1213,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
@@ -1306,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.
@@ -1347,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
@@ -1426,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
@@ -1500,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:

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

@@ -95,8 +95,8 @@
 #   guardrails/brf-<domain>/frontend/*.md — the code-derived lane rule set, the detail
 #       layer under those UX-* principles, wired into tech-rule-bindings.md under the lane's
 #       three headings: `## /aw-spec-ui-constitution` (what a later /appweaver constitution
-#       re-ratifies the UI half from), `## /aw-spec-plan-ui` and `## /aw-spec-implement-ui`
-#       (what the frontend lane of `plan` and of `implement` load).
+#       re-ratifies the UI half from), `## /aw-spec-plan-frontend` and
+#       `## /aw-spec-implement-frontend` (what the frontend lane of `plan` and of `implement` load).
 #   .appweaver/templates/overrides/ui-design-template.md + ui-delta-design-template.md — the
 #       lane's own document pair, reverse-engineered from the UI source the same way the
 #       service pair is reverse-engineered from the service code. The lane is governed by a
@@ -149,7 +149,7 @@
 # =============================================================================
 
 name: aw-spec-onboard
-description: Onboard an existing codebase for brownfield DEVELOPMENT — a deterministic whole-repo scan produces a high-level OKF feature map (folders/concepts) PLUS the project-level governance scaffold (split constitution + guardrails/brf-<domain>/ with its DOMAIN rule files at domain/ + domain-rule-bindings + code-derived TECHNICAL rule files at service/ + tech-rule-bindings + activated domain), all provisional-from-scan. The first context authors that tier; every later context amends it additively from its own code (new rules, principles and map entries — never a rewrite, renumbering or deletion; a contradiction is recorded as a Divergence note), and a tier that does not exist yet, such as a lane declared after an earlier onboard, is authored in full. Naming an already-onboarded context re-runs that governance pass alone. Where the scan finds a frontend lane in the CODE, it also authors that lane's half — constitution.ui.md (UX-*) — and its code-derived rule files at brf-<domain>/frontend/, mapped under `## /aw-spec-ui-constitution`, `## /aw-spec-plan-ui` and `## /aw-spec-implement-ui`; a backend-only repo gets none of it. Every rule tier is reverse-engineered from the CODE alone (never a greenfield rule file), evidenced-only, and WIRED per-workflow so the whole forward pipeline AND adopt govern against THIS codebase — never a greenfield fallback. It also reverse-engineers the repo's own technical structure into a project-specific design + delta-design template pair, installed as the project template overrides, and — where the lane exists — the frontend lane's own pair from the UI source. Every authoring step is shaped by a NEUTRAL rev-templates skeleton; no greenfield constitution, rule file or document template is ever placed in context. Accepts an optional concerns list to look for (onboard decides which are actually present). Reads any declared lane, never writes one. No migration content; never modifies source.
+description: Onboard an existing codebase for brownfield DEVELOPMENT — a deterministic whole-repo scan produces a high-level OKF feature map (folders/concepts) PLUS the project-level governance scaffold (split constitution + guardrails/brf-<domain>/ with its DOMAIN rule files at domain/ + domain-rule-bindings + code-derived TECHNICAL rule files at service/ + tech-rule-bindings + activated domain), all provisional-from-scan. The first context authors that tier; every later context amends it additively from its own code (new rules, principles and map entries — never a rewrite, renumbering or deletion; a contradiction is recorded as a Divergence note), and a tier that does not exist yet, such as a lane declared after an earlier onboard, is authored in full. Naming an already-onboarded context re-runs that governance pass alone. Where the scan finds a frontend lane in the CODE, it also authors that lane's half — constitution.ui.md (UX-*) — and its code-derived rule files at brf-<domain>/frontend/, mapped under `## /aw-spec-ui-constitution`, `## /aw-spec-plan-frontend` and `## /aw-spec-implement-frontend`; a backend-only repo gets none of it. Every rule tier is reverse-engineered from the CODE alone (never a greenfield rule file), evidenced-only, and WIRED per-workflow so the whole forward pipeline AND adopt govern against THIS codebase — never a greenfield fallback. It also reverse-engineers the repo's own technical structure into a project-specific design + delta-design template pair, installed as the project template overrides, and — where the lane exists — the frontend lane's own pair from the UI source. Every authoring step is shaped by a NEUTRAL rev-templates skeleton; no greenfield constitution, rule file or document template is ever placed in context. Accepts an optional concerns list to look for (onboard decides which are actually present). Reads any declared lane, never writes one. No migration content; never modifies source.
 version: 2.3.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
@@ -1036,8 +1036,10 @@ workflow:
           charter; a later step in this same run authors it, so wire the bullet now), then the
           domain identity/regulatory/interop files → domain principles.
         - `## /aw-spec-specify`      — the FULL domain set (specify models the domain, lifts CN-/DC-/IC-).
-        - `## /aw-spec-plan`       — `_None — plan loads no domain file. Domain reaches plan through the spec and the context's domain-model.md._`
-        - `## /aw-spec-implement`    — `_None — implement loads no domain file. Domain reaches implement through the lane plans and the context's domain-model.md._`
+        - `## /aw-spec-plan-backend`       — `_None — the service lane of plan loads no domain file. Domain reaches it through the spec and the context's domain-model.md._`
+        - `## /aw-spec-plan-frontend`      — `_None — the frontend lane of plan loads no domain file. Domain reaches it through the spec and the context's domain-model.md._`
+        - `## /aw-spec-implement-backend`  — `_None — the service lane of implement loads no domain file. Domain reaches it through backend-plan.md and the context's domain-model.md._`
+        - `## /aw-spec-implement-frontend` — `_None — the frontend lane of implement loads no domain file. Domain reaches it through frontend-plan.md and the context's domain-model.md._`
         - `## /aw-spec-gate`         — the conformance-checklist set (the *.domain.md files).
       Each bullet is a workspace-relative path `- guardrails/{{domain_slug}}/domain/<file>`.
       Write ONLY inside guardrails/{{domain_slug}}/ (domain/ + the map). Report the
@@ -1367,7 +1369,7 @@ workflow:
         existing files (frontmatter origin: reverse-engineered, generated_by:
         {{generated_by}}, concern); every rule cites a UI code coordinate from this
         context and the UX numeral it details. Wire it into tech-rule-bindings.md under
-        `## /aw-spec-plan-ui` and/or `## /aw-spec-implement-ui` as its rules serve
+        `## /aw-spec-plan-frontend` and/or `## /aw-spec-implement-frontend` as its rules serve
         planning or generating, and give it its table row. frontend/ui-constitution.md
         stays the only file under `## /aw-spec-ui-constitution` that is not also a
         concern file.
@@ -1580,8 +1582,8 @@ workflow:
         named after the concern the code exhibits. Wire it into
         domain-rule-bindings.md under `## /aw-spec-specify` and `## /aw-spec-gate`
         (plus `## /aw-spec-constitution` for an identity / regulatory file), as the
-        existing files are wired. `## /aw-spec-plan` and `## /aw-spec-implement` keep
-        loading no domain file.
+        existing files are wired. The plan and implement headings (`-backend` and
+        `-frontend`) keep loading no domain file.
       - NEW rules appended to an EXISTING rule file, where this context's code enforces
         a rule of that concern the file does not state — each citing this context's code
         and marked `(context: {{bc}})`. Mark unresolved specifics `PROVISIONAL —
@@ -1859,12 +1861,11 @@ workflow:
       ONLY a heading you have a generated file for (an absent heading soft-continues → loads
       nothing):
         - `## /aw-spec-specify`         — EXACTLY ONE bullet: `service/domain-modelling.md`, the modelling methodology. NEVER an architecture / persistence / codegen / security file here — specify is the domain phase and any technology rule under this heading breaks its domain purity. Omit the heading only if you did not write domain-modelling.md.
-        - `## /aw-spec-plan`          — the as-built architecture / cross-cutting rules the SERVICE lane's plan author mediates the spec against.
-        - `## /aw-spec-implement`        — the code-generation / convention set the SERVICE lane's generator builds against (from backend-plan.md).
-        - `## /aw-spec-implement-delta`  — the same set for the service lane on the DELTA path. `implement` is one command that keys this heading when it is generating a change's delta plan and the one above when it is generating the master, so a project that wants the same rules on both paths repeats them here.
+        - `## /aw-spec-plan-backend`     — the as-built architecture / cross-cutting rules the SERVICE lane's plan author mediates the spec against.
+        - `## /aw-spec-implement-backend` — the code-generation / convention set the SERVICE lane's generator builds against (from backend-plan.md), on both the master and the delta path.
         - `## /aw-spec-build`            — the layering + convention rules the compile-fixer respects.
         - `## /aw-spec-analyze-slice`    — the conformance rules the plan↔code gate validates against.
-        - `## /aw-spec-adopt`            — the technical reference set the reversed plan mediates against (a subset of plan's).
+        - `## /aw-spec-adopt-backend`    — the technical reference set the reversed backend plan mediates against (a subset of `## /aw-spec-plan-backend`'s).
         - `## /aw-spec-constitution`     — the standards a later `/appweaver constitution` re-ratifies the TECHNICAL half from. You authored that half from code evidence before these files existed; this heading is what makes a re-run author from THIS project's rules rather than from an empty set. Ratifiable standards only, no worked `examples/` sample, no domain file.
         - `## /aw-spec-run`              — the runtime / execution conventions the app-run step honors (add ONLY if the code evidences a runtime/hosting concern file; NOT data-migration — migration is the deferred later phase).
       Each bullet is a
@@ -1925,7 +1926,7 @@ workflow:
   # (or creates the file, in a project with no service lane). `## /aw-spec-ui-constitution`
   # is what makes a later /appweaver constitution re-ratify the UI half from THIS project's
   # lane rules, and the authoritative signal that the project HAS a frontend lane.
-  # `## /aw-spec-plan-ui` and `## /aw-spec-implement-ui` are what the frontend lane of
+  # `## /aw-spec-plan-frontend` and `## /aw-spec-implement-frontend` are what the frontend lane of
   # `plan` and of `implement` load; without them that lane plans and generates against no
   # project rule at all.
   - id: ctx_ui_pack
@@ -1997,10 +1998,10 @@ workflow:
            `frontend/ui-constitution.md` first. It is what a later /appweaver constitution
            re-ratifies the UI half from, and the authoritative signal that the project has a
            frontend lane; precede the bullets with a short HTML comment saying both.
-        2. `## /aw-spec-plan-ui` — the files the FRONTEND lane of `plan` authors
+        2. `## /aw-spec-plan-frontend` — the files the FRONTEND lane of `plan` authors
            frontend-plan.md against: those whose rules decide a feature's screens, navigation,
            client state, interaction states, forms, accessibility and service binding.
-        3. `## /aw-spec-implement-ui` — the files the FRONTEND lane of `implement` generates
+        3. `## /aw-spec-implement-frontend` — the files the FRONTEND lane of `implement` generates
            code against, on the master and the delta path alike: those whose rules govern
            component conventions, state and data fetching, styling, forms and UI tests.
       A file whose rules carry both a planning half and a generating half is listed under both
@@ -2060,7 +2061,7 @@ workflow:
     on_error: continue
     script: { ref: actions }
     subcommand: resolve-tech
-    args: ["--command", "aw-spec-plan-ui"]
+    args: ["--command", "aw-spec-plan-frontend"]
     outputs:
       - { name: ui_plan_rules, from: "$.candidates" }
   - id: warn_ui_plan_wiring
@@ -2070,7 +2071,7 @@ workflow:
     on_empty: continue
     on_empty_message: >
       guardrails/{{domain_slug}}/tech-rule-bindings.md maps nothing under
-      `## /aw-spec-plan-ui`, so the frontend lane of /appweaver plan will author
+      `## /aw-spec-plan-frontend`, so the frontend lane of /appweaver plan will author
       frontend-plan.md with no project rule file. Add the heading, bulleting the
       frontend/ files whose rules shape a feature's screens, state and interactions.
   - id: probe_ui_impl_wiring
@@ -2079,7 +2080,7 @@ workflow:
     on_error: continue
     script: { ref: actions }
     subcommand: resolve-tech
-    args: ["--command", "aw-spec-implement-ui"]
+    args: ["--command", "aw-spec-implement-frontend"]
     outputs:
       - { name: ui_impl_rules, from: "$.candidates" }
   - id: warn_ui_impl_wiring
@@ -2089,7 +2090,7 @@ workflow:
     on_empty: continue
     on_empty_message: >
       guardrails/{{domain_slug}}/tech-rule-bindings.md maps nothing under
-      `## /aw-spec-implement-ui`, so the frontend lane of /appweaver implement will
+      `## /aw-spec-implement-frontend`, so the frontend lane of /appweaver implement will
       generate UI code with no project rule file. Add the heading, bulleting the
       frontend/ files whose rules govern component, state, styling and test conventions.
 

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

@@ -17,11 +17,14 @@
 # against no declared stack invents its own.
 #
 # ONE COMMAND, TWO LANES, TWO RULE SETS. The lanes take their rules from different
-# headings of tech-rule-bindings (`## /aw-spec-plan` for the service, `## /aw-spec-plan-ui`
-# for the frontend), and the frontend set is loaded ONLY when that lane is declared — so
-# a backend-only project sees exactly the rules it did before. In a two-lane project both
-# sets are sticky for the whole run; the lane boundary is held by the prompts instead,
-# and §5 Contract Binding is where it is stated.
+# headings of tech-rule-bindings (`## /aw-spec-plan-backend` for the service,
+# `## /aw-spec-plan-frontend` for the frontend), and each set is loaded only when its lane
+# is declared. The two are never loaded together: the service set loads at step 1, before
+# the backend sections, and the frontend set REPLACES it at the lane swap before the
+# frontend sections — tech_select_ui_master on the master path, the delta-plan module's
+# own swap on the change path. Each plan is therefore authored with only its own lane's
+# rule set in its envelope. Where the two plans meet is stated in the frontend plan's
+# §5 Contract Binding, which binds to the service's published surface only.
 #
 # RENAMED FROM `design`. design.md → backend-plan.md, design.ui.md → frontend-plan.md,
 # and the former separate `design-ui` command is FOLDED IN here. The scaffold MIGRATES a
@@ -204,15 +207,15 @@ workflow:
     on_false_message: "No lane is declared in .appweaver/stacks.json, so there is nothing to plan. Run /appweaver select-stack and declare the backend stack, the frontend stack, or both — plus each one's lane root folder — then re-run plan. The declaration is what tells this phase which documents to write; a plan written against no declared stack invents its own."
 
   # 1. TECHNICAL rule files → sticky standards (configuration, not hardcoded).
-  #    The service lane's set is loaded under `## /aw-spec-plan`; the frontend lane's under
-  #    `## /aw-spec-plan-ui`, and ONLY when that lane is declared — so a backend-only
+  #    The service lane's set is loaded under `## /aw-spec-plan-backend`; the frontend lane's
+  #    under `## /aw-spec-plan-frontend`, and ONLY when that lane is declared — so a backend-only
   #    project's standards are exactly what they were before the two commands merged.
   #    No blocking gate: an unconfigured project soft-continues (the constitutions still
   #    carry each lane's ratified base).
   #
   #    ONLY THE BACKEND'S RULES LOAD HERE. The frontend's used to load alongside them,
   #    before either lane authored anything, and sticky standards only accumulate — so the
-  #    service plan was authored with `## /aw-spec-plan-ui` in its envelope and the
+  #    service plan was authored with `## /aw-spec-plan-frontend` in its envelope and the
   #    experience plan with the service set. Each prompt names its lane, but it said so
   #    inside an envelope that contradicted it. The UI set now loads at the frontend
   #    boundary instead, with `replace`, in both places a frontend document is authored:
@@ -222,7 +225,7 @@ workflow:
     condition: "{{be_declared}} == true"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-plan }
+    with: { command: aw-spec-plan-backend }
 
   # 2. Resolve the current feature and require its spec.
   - id: feature_paths
@@ -617,6 +620,10 @@ workflow:
         as field shapes. That section is the ONLY part of this document the frontend plan
         may read; keep it complete and self-contained, because a contract the UI needs and
         this document never states becomes a client-side workaround.
+      - NAME EVERY ENDPOINT. Each §3 endpoint carries an **Operation id** — its name in the
+        service's published API document (e.g. `CreatePatient`), unique across the
+        service and never reused. The frontend plan cites it, and implement gives the
+        endpoint exactly this id, so the two lanes meet on it.
       - CONSTITUTION-MANDATED CROSS-CUTTING (from the loaded technical constitution, NOT
         the spec): a NON-NEGOTIABLE technical principle you must apply that has NO
         per-feature spec id. APPLY it (it is non-negotiable), and because it is not
@@ -704,6 +711,10 @@ workflow:
       - PUBLISH THE SURFACE THE FRONTEND LANE BINDS TO: the section carrying this feature's
         endpoints states each contract as field shapes, completely, because it is the only
         part of this document the frontend plan may read.
+      - NAME EVERY ENDPOINT with its route, verb and operation id — its name in the
+        service's published API document, unique across the service. Where the code
+        already gives the endpoint one, record THAT id exactly as the code spells it; the
+        frontend plan cites it and implement finds the endpoint by it.
       - CONSTITUTION-MANDATED CROSS-CUTTING (from the loaded technical constitution, NOT
         the spec): a NON-NEGOTIABLE technical principle with no per-feature spec id —
         APPLY it, and LOG it as a §5 DA-n whose basis cites the mandating principle
@@ -773,6 +784,9 @@ workflow:
         workarounds are DECISIONS THIS TEAM MADE, not derivations from the spec — keep
         every one, with its id and its basis, unless the thing it decided about is gone.
         Never renumber a surviving entry: its id is cited elsewhere.
+      - OPERATION IDS ARE STABLE. Every endpoint keeps the operation id it already has —
+        the frontend plan and the built code both use it. A new endpoint gets one, unique
+        across the service; an endpoint without one gets one now.
       - THE CODE THAT EXISTS IS THE WHAT-IS AUTHORITY. {{source_count}} source file(s)
         realise this feature: {{source_files}}. READ them, and where the plan and the code
         disagree about STRUCTURE, the code is what is actually there — conform to it and
@@ -788,7 +802,7 @@ workflow:
   # ══════════════ THE LANE SWAP — the frontend's rules replace the backend's ═══
   # Both tech-select includes used to run up at step 4, before either lane authored
   # anything, and sticky standards only accumulate — so on a full-stack run the backend
-  # plan was authored with `## /aw-spec-plan-ui` in its envelope and the frontend plan with
+  # plan was authored with `## /aw-spec-plan-frontend` in its envelope and the frontend plan with
   # the service set. Each prompt names its lane, but it did so inside an envelope that
   # contradicted it, and the envelope is the half the model cannot argue with.
   #
@@ -800,7 +814,7 @@ workflow:
     condition: "{{fe_mode}} != skip"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-plan-ui, replace: "true" }
+    with: { command: aw-spec-plan-frontend, replace: "true" }
 
   # ═══════════ FRONTEND LANE — bootstrap, greenfield experience template ═══════
   # The experience twin of the service plan, and the MEDIATOR between spec.md and the
@@ -867,6 +881,10 @@ workflow:
         DELTA raised back to the service lane under "Contract deltas needed" — never a
         workaround in the client. Where no service plan is in context, bind from the
         spec's IC- surface and record that as a §8 DA-n.
+      - EVERY §5 ROW CITES ITS OPERATION ID, copied exactly from the endpoint's
+        **Operation id** in the backend plan's §3 — implement looks the endpoint up by it
+        in the service's exported API document. Where no service plan names one, write
+        `—` and record it in the same §8 DA-n.
       - CONSTITUTION-MANDATED CROSS-CUTTING (from the loaded UI constitution, NOT the
         spec): a NON-NEGOTIABLE UX principle you must apply that has no per-feature spec
         id. APPLY it, and because it is not spec-derived, LOG it as a §8 DA-n whose
@@ -952,6 +970,9 @@ workflow:
         states. Cite them; do not restate, re-derive or contradict them, and introduce no
         server-side behaviour. What the experience needs and the surface lacks is a
         contract delta raised back to the service lane, never a client workaround.
+      - EVERY BINDING ROW CITES ITS OPERATION ID, copied exactly from the backend plan —
+        implement looks the endpoint up by it in the service's exported API document.
+        Where no service plan names one, write `—` and record it as a DA-n.
       - CONSTITUTION-MANDATED CROSS-CUTTING with no per-feature spec id: apply it, and
         log it as a DA-n citing the mandating principle ("per constitution.ui.md
         UX-<n>"). Do not fabricate a spec id for it and do not leave it uncited.
@@ -1010,6 +1031,9 @@ workflow:
         — the spec's IC- ids and, where the backend plan is in context, the API contracts
         it states. What the experience needs and the surface lacks is a contract delta
         raised back to the service lane, never a client workaround.
+      - EVERY BINDING ROW CITES ITS OPERATION ID, copied exactly from the backend plan; a
+        row that has none yet gets it now, and a row whose id the backend plan no longer
+        has is re-bound. Where no service plan names one, write `—` with a DA-n.
       - TECHNOLOGY-AGNOSTIC: no framework, router, state library, component library or
         styling approach — responsibilities, field shapes, events and states only.
       - ADD ONE Change History row for this re-derivation, describing what MOVED and why.