aw-spec-cli 0.1.32 → 0.1.34

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

@@ -2,8 +2,9 @@
 # aw-spec-adopt (orchestrator) — the JUST-IN-TIME per-feature step of Brownfield DEV
 #
 # Develop an EXISTING feature by first reverse-engineering ONE aggregate / vertical
-# slice from its code into a living spec.md, the bounded context's domain-model.md and
-# aligned lane plans (+ a source-map.md sidecar), THEN reconciling this feature's evidence into the project governance that
+# slice from its code into a living spec.md, the bounded context's domain-model.md, the
+# API the slice publishes (api-plan.md) and aligned lane plans (+ a source-map.md sidecar),
+# THEN reconciling this feature's evidence into the project governance that
 # /appweaver onboard established. Adopt is the inverse of implement: implement reads the
 # plans + the model and generates code; adopt reads code and generates the spec, the model
 # and the plans — equally a reasoning step, stamped `origin: reverse-engineered` with
@@ -28,9 +29,12 @@
 # project default). So adopt = reverse an EXISTING feature; the forward pipeline = a
 # new one. Both then evolve through the CR delta loop.
 #
-# The reverse output is a NORMAL feature: spec.md, domain-model.md and backend-plan.md /
-# frontend-plan.md are the very documents the CR delta loop + forward pipeline consume
-# unchanged — under those names, so nothing downstream needs a brownfield special case.
+# The reverse output is a NORMAL feature: spec.md, domain-model.md, api-plan.md and
+# backend-plan.md / frontend-plan.md are the very documents the CR delta loop + forward
+# pipeline consume unchanged — under those names, so nothing downstream needs a brownfield
+# special case. The API plan is written from the kit's api-plan-template, which onboard
+# does not override: its endpoint block form is the one the contract scripts read in every
+# project, so only the plans around it follow the code's own structure.
 # plan-scaffold's backend/frontend lanes also MIGRATE a legacy design.md / design.ui.md left
 # by an adopt that ran before the rename, so an already-adopted repo is carried forward. All brownfield provenance
 # lives in `origin:` frontmatter + the source-map sidecar. Adopt inits
@@ -71,7 +75,24 @@
 # =============================================================================
 
 name: aw-spec-adopt
-description: The JIT per-feature step of brownfield development — reverse-engineer ONE existing feature into a living spec.md, an aggregate section in the bounded context's shared domain-model.md, and backend-plan.md (+ frontend-plan.md where a frontend lane is declared and this slice owns part of its surface) + source-map.md (origin reverse-engineered, per-item confidence, code-derived plan template), then COMPLETE its shallow OKF concept (deepen it to the reversed reality + link the deep artifacts) and record its cross-slice edges. The spec cites BR-nnn by id and the model defines them, exactly as on the greenfield path, so a reversed slice is checkable by the same gates as any other. Fidelity gate is spec + model + plans vs code, and an invented entity, boundary or invariant is a fabrication exactly as an invented FR- is; the review is reported for out-of-band closure. Every reverse step is scoped to the feature's own operations from the confirmed boundary map, so two features over one aggregate never claim the same operation, and the spec continues the context's BR-nnn numbering from its domain model. Where a frontend lane is declared and this slice owns none of its surface, the feature records lanes=backend so later phases neither author nor demand a frontend plan for it. The governance reconcile — carrying this feature's real evidence into the provisional rule files + constitution onboard wrote — is HELD (reconcile_governance=false), so an ordinary run does not touch the governance tier. A NEW feature is authored via the forward pipeline instead. Output is a normal feature for the CR + forward loop.
+description: The JIT per-feature step of brownfield development — reverse-engineer ONE existing feature into a living spec.md, an aggregate section in the bounded context's shared domain-model.md, and its lane plans — api-plan.md (the endpoints the slice publishes, with the operation ids the code gives them) and backend-plan.md where a backend lane is declared and the slice has service code, frontend-plan.md where a frontend lane is declared and this slice owns part of its surface — + source-map.md (origin reverse-engineered, per-item confidence, code-derived plan template), then COMPLETE its shallow OKF concept (deepen it to the reversed reality + link the deep artifacts), record its cross-slice edges and draw its API plan into api-draft.json, the API the frontend lane binds to. The spec cites BR-nnn by id and the model defines them, exactly as on the greenfield path, so a reversed slice is checkable by the same gates as any other. Fidelity gate is spec + model + plans vs code, and an invented entity, boundary or invariant is a fabrication exactly as an invented FR- is; the review is reported for out-of-band closure. Every reverse step is scoped to the feature's own operations from the confirmed boundary map, so two features over one aggregate never claim the same operation, and the spec continues the context's BR-nnn numbering from its domain model. Where a frontend lane is declared and this slice owns none of its surface, the feature records lanes=backend so later phases neither author nor demand a frontend plan for it. The governance reconcile — carrying this feature's real evidence into the provisional rule files + constitution onboard wrote — is HELD (reconcile_governance=false), so an ordinary run does not touch the governance tier. A NEW feature is authored via the forward pipeline instead. Output is a normal feature for the CR + forward loop.
+# 2.5.0 — the endpoints the slice publishes are reversed into the feature's own api-plan.md,
+#         before the backend plan, which realises them and points to it; the frontend plan
+#         takes its operation ids from the API plan and never reads the backend plan; the
+#         source-map and the fidelity check cover the API plan too; once fidelity passes,
+#         the API plan is drawn into api-draft.json, so the slice is in the frontend's
+#         combined document from the start.
+# 2.3.0 — the SERVICE half is reversed only where the slice has one (svc_lane: a backend lane
+#         is declared and the slice has service files), the twin of ui_lane. A frontend-only
+#         project gets no backend plan and no cross-slice edges, and its model is read from
+#         the UI files; a UI-only slice in a repo with both lanes records lanes=[frontend].
+#         A failed fidelity check names the two ways to resolve it — re-adopt, or correct
+#         the documents by hand — and what each leaves behind.
+# 2.2.0 — the reversed plans take part in the API ledger between the lanes: the backend plan
+#         writes each endpoint the slice publishes as an endpoint block (`#### `VERB /route``
+#         + **Operation id**, the id the code publishes — `—` and a DA-n where it publishes
+#         none, never an invented one) with a "Requests from the frontend lane" table, and the
+#         frontend plan's Contract Binding rows cite those ids.
 # 2.1.0 — every reverse step is scoped to the FEATURE, not its aggregate: the boundary map's
 #         operation list (and a sibling feature's operations, which are not this one's)
 #         reaches the spec, model, plan, UI plan, source-map and fidelity steps. The spec step
@@ -87,7 +108,7 @@ description: The JIT per-feature step of brownfield development — reverse-engi
 # 1.3.0 — reverse design scaffolds from the DEFAULT `design-template` (onboard's code-derived
 #         override) instead of the never-shipped `brownfield-design-template`, unifying the
 #         whole brownfield pipeline on one code-derived template.
-version: 2.1.0
+version: 2.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -128,8 +149,12 @@ vars:
   be_declared: "false"
   fe_no_surface: "false"       # a frontend lane is declared, this slice owns none of its surface, and a backend lane carries it
   feature_lanes: ""            # what record_lanes wrote — empty when the feature follows every declared lane
+  xref_edge_count: "0"         # xref_record runs only where the slice has a service half
   fe_root: ""
   ui_lane: "false"             # THIS slice reverses a UI half: a frontend lane is declared AND the slice owns UI files
+  svc_lane: "false"            # THIS slice reverses a SERVICE half: a backend lane is declared AND the slice has service files
+  be_no_surface: "false"       # a backend lane is declared, this slice has no service code, and a frontend lane carries it
+  model_files: ""              # what the model is reversed from: the service files, or the UI files on a slice with none
   ui_count: "0"                # how many UI files the concept attributes to this aggregate (aw-inventory ui_source_files)
   ui_source_files: ""
   frontend_plan: ""
@@ -149,6 +174,21 @@ vars:
   # left by an earlier adopt, so a repo that was adopted before the rename is carried
   # forward rather than left with two spellings of one master.
   backend_plan: ""
+  # THE API THE SLICE PUBLISHES — its own document, reversed before the backend plan, which
+  # realises each endpoint. `api_blocked` is the scaffold refusing because a backend plan
+  # already in the folder carries the endpoints: that plan keeps them for this run, as
+  # before API plans existed, and the frontend plan reads it in their place (`api_read`).
+  api_plan: ""
+  api_blocked: "false"
+  api_reverse: "false"
+  api_read: ""
+  draft_path: ""               # api-draft.json, drawn after fidelity passes (contract_draft)
+  draft_plan: ""
+  draft_ops: "0"
+  draft_unread: "0"
+  draft_unread_text: ""
+  draft_clean: "true"
+  be_api_rule: "THE ENDPOINTS ARE IN api-plan.md (in context), reversed just before this document from the same code: the API contract the frontend lane binds to. Do NOT restate them here — the §2 axis that publishes them carries the one line pointing to api-plan.md, and where the template has an endpoint block or a requests table there (a template generated before API plans existed), that line goes in their place. REALISE every endpoint instead: each names under **Maps to** the code unit that serves it, and that unit is this document's element, under the same name, with request and response shapes that match the endpoint's. An endpoint with no element here is unrealised. The traceability spine cites an endpoint as `VERB /route`."
   # THE BOUNDED CONTEXT'S DOMAIN MODEL — shared by every feature in the context, and the
   # authority on the aggregate root, its entities and the TEXT of every BR-nnn. Reversed
   # here in the same run as the spec, exactly as greenfield `specify` authors the two
@@ -157,6 +197,10 @@ vars:
   context_dir: ""
   domain_model: ""
   domain_model_exists: "false"
+  model_guard_ok: "false"      # model-guard-check's verdict on the reverse_model rewrite. DEFAULTS
+                               # TO REFUSE: only the check's own `ok` lets the run past the gate
+  model_guard_losses: ""       # what the rejected rewrite lost, one clause per item
+  model_guard_rejected: ""     # where the rejected rewrite was kept
   spec_exists: "false"
   fidelity_ok: "false"
   rulemap_exists: "false"      # governance-present signal (onboard ran) — bound from resolve-domain
@@ -424,14 +468,6 @@ workflow:
     outputs:
       - { name: domain_model, from: "$.domain_model" }
 
-  - id: scaffold_plan
-    action: execute_script
-    script: { ref: actions }
-    subcommand: plan-scaffold
-    args: ["--feature-dir", "{{feature_dir}}", "--lane", "backend"]   # `design-template` = onboard's code-derived override (greenfield base if onboard has not run)
-    outputs:
-      - { name: backend_plan, from: "$.plan_doc" }
-
   - id: version_init
     action: execute_script
     script: { ref: actions }
@@ -502,6 +538,100 @@ workflow:
     outputs:
       - { name: feature_lanes, from: "$.lanes" }
 
+  # 2d. DOES THIS SLICE HAVE A SERVICE HALF? The twin of 2b: a backend lane must be DECLARED
+  #     and this aggregate must have service files (the concept's source_files). A
+  #     frontend-only project declares no backend lane, and its concepts list every file as
+  #     ui_source_files, so a backend plan there would describe code that does not exist and
+  #     the fidelity gate would score it as fabricated. Three ordered sets, as in 2b.
+  - id: svc_lane_off
+    action: set
+    vars: { svc_lane: "false" }
+  - id: svc_lane_on
+    action: set
+    condition: "{{be_declared}}"
+    vars: { svc_lane: "true" }
+  - id: svc_lane_no_code
+    action: set
+    condition: "{{source_count}} == 0"
+    vars: { svc_lane: "false" }
+
+  # 2e. RECORD A UI-ONLY SLICE in a repo that declares both lanes — the twin of 2c, so plan
+  #     and the analyze gates do not demand a backend plan for a slice with no service code.
+  - id: be_no_surface_off
+    action: set
+    vars: { be_no_surface: "false" }
+  - id: be_no_surface_declared
+    action: set
+    condition: "{{be_declared}}"
+    vars: { be_no_surface: "true" }
+  - id: be_no_surface_has_code
+    action: set
+    condition: "{{source_count}} != 0"
+    vars: { be_no_surface: "false" }
+  - id: be_no_surface_no_frontend
+    action: set
+    condition: "{{ui_lane}} != true"
+    vars: { be_no_surface: "false" }
+  - id: record_lanes_frontend
+    condition: "{{be_no_surface}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: feature-lanes
+    args: ["--feature-dir", "{{feature_dir}}", "--set", "frontend"]
+    outputs:
+      - { name: feature_lanes, from: "$.lanes" }
+
+  # What the domain model is reversed FROM. The service files where the slice has them; a
+  # slice with none keeps its domain in the UI code — the types, states and rules a
+  # frontend-only app holds — so the model is read from those.
+  - id: model_files_service
+    action: set
+    vars: { model_files: "{{source_files}}" }
+  - id: model_files_ui
+    condition: "{{svc_lane}} != true"
+    action: set
+    vars: { model_files: "{{ui_source_files}}" }
+
+  # THE API PLAN FIRST, where the slice has a service half — scaffolded from the kit's
+  # api-plan-template before the backend plan, as `plan` does it: the scaffold refuses
+  # (`blocked`) while a backend plan in the folder carries the API, and a backend plan
+  # scaffolded from a template generated before API plans existed carries an empty requests
+  # table, so it must not be there yet.
+  - id: scaffold_api_plan
+    condition: "{{svc_lane}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--lane", "api"]
+    outputs:
+      - { name: api_plan,    from: "$.plan_doc" }
+      - { name: api_blocked, from: "$.blocked" }
+
+  - id: scaffold_plan
+    condition: "{{svc_lane}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--lane", "backend"]   # `design-template` = onboard's code-derived override (greenfield base if onboard has not run)
+    outputs:
+      - { name: backend_plan, from: "$.plan_doc" }
+
+  # WHERE THE API IS REVERSED, and what the frontend plan reads of the service: the API plan
+  # just scaffolded — or, where the scaffold refused, the backend plan, which then keeps its
+  # endpoint blocks for this run. Nothing where the slice has no service half.
+  - id: api_reverse_arm
+    condition: "{{svc_lane}} == true"
+    action: set
+    vars: { api_reverse: "true", api_read: "{{api_plan}}" }
+  - id: api_reverse_blocked
+    condition: "{{api_blocked}} == true"
+    action: set
+    vars:
+      api_plan: ""
+      api_reverse: "false"
+      api_read: "{{backend_plan}}"
+      be_api_rule: "EVERY ENDPOINT THIS FEATURE PUBLISHES IS AN ENDPOINT BLOCK IN THIS DOCUMENT — a backend plan already in the folder carries the API, so it stays here for this run — in the §2 axis that publishes it: the heading `#### `VERB /route` — <purpose> · Serves <US/FR ids>`, then **Operation id**, Auth, Request, Success, the Errors table and Maps to, exactly as the template's endpoint block — never a row in a table of endpoints. The contract scripts read this form: the API draft is written from the headings, and the request ledger between the lanes reads the operation ids. The **Operation id** is the id the code publishes the endpoint under, spelled exactly as the code spells it; the boundary map records each operation's published id where the code declares one ('published as …' above). Where the code publishes none, write `—` and record a §5 DA-n saying the endpoint has no published operation id — never invent one: the service's as-built API document would not carry it, so the frontend would bind to an id the service does not answer, and analyze-slice would report it. After the endpoint blocks, a `#### Requests from the frontend lane` heading with `None` under it: a frontend reversed from the same code binds only to what the service already serves, so no request is open yet."
+
   # Scaffold the LANE's plan from ITS template pair (--lane frontend resolves
   # ui-design-template -> frontend-plan.md), the twin of scaffold_plan above. onboard
   # GENERATED that override from this repo's own UI source, so the reversed frontend plan
@@ -671,6 +801,18 @@ workflow:
       - { path: "{{spec_file}}" }                 # the reversed spec — the BR-nnn ids this model must define
       - { path: "{{concept_path}}" }              # source_files + seam
       - { path: .appweaver/memory/constitution.domain.md, optional: true }
+
+  # THE REWRITE IS CHECKED. The engine writes the agent's reply over the WHOLE model, which
+  # on a context's second slice holds the sections, BR-/XBR- rules and ledger rows the
+  # features adopted or specified before it rely on. The snapshot copies it aside; the check
+  # after the step compares the two (python/aw-model-guard.py) and, on a loss, puts the
+  # model back and keeps the rewrite as domain-model.rejected.md.
+  - id: reverse_model_snapshot
+    action: execute_script
+    script: { ref: actions }
+    subcommand: model-guard-snapshot
+    args: ["--model", "{{domain_model}}"]
+
   - id: reverse_model
     action: agent_author
     include_standards: false                       # the technical/arch sticky set is for the plans, never the model
@@ -714,6 +856,12 @@ workflow:
         already there — other specs cite their ids, and a renumbered BR breaks every
         citation silently. Add `{{feature_name}}` to the `Serving specs` line of any
         existing aggregate this slice also acts on.
+      - A SCRIPT COMPARES YOUR FILE WITH THE MODEL AS IT WAS, and puts the old one back if
+        any of these is gone: an `## Aggregate:` section under its name; a BR-n or XBR-n,
+        in the same section, with the same rule text, defined once; a name on an
+        aggregate's `Serving specs` line; a Ubiquitous Language term; a context the
+        Context Map names; a Change History row; the Context version. Add to any of them
+        freely; never remove, rename, renumber, move or reword one.
       - MODEL WHAT THE CODE EXHIBITS, NOT WHAT GOOD DESIGN WOULD WANT. Classify entities
         vs value objects by whether the code gives the thing an IDENTITY; draw the
         boundary where the code actually draws it (what it loads and saves together).
@@ -734,6 +882,96 @@ workflow:
       - Add `origin: reverse-engineered` near the identity block. Do NOT write the Context
         version or the Change History version column — scripts stamp those.
 
+      Source files to read (the slice's code — its UI files where it has no service code,
+      the one place a frontend-only app keeps its types, states and rules): {{model_files}}
+
+  - id: reverse_model_check
+    action: execute_script
+    script: { ref: actions }
+    subcommand: model-guard-check
+    args: ["--model", "{{domain_model}}"]
+    outputs:
+      - { name: model_guard_ok,       from: "$.ok" }
+      - { name: model_guard_losses,   from: "$.losses_text" }
+      - { name: model_guard_rejected, from: "$.rejected" }
+
+  # On a stop the model is already restored; this slice's spec.md is written, so the
+  # already-adopted guard would refuse a plain re-run — the feature folder goes first.
+  - id: reverse_model_guard
+    action: verify_context
+    require_true: model_guard_ok
+    on_false: stop
+    on_false_message: "The domain model lost content other features rely on, so {{domain_model}} was put back as it was before this run. Lost: {{model_guard_losses}}. The rejected rewrite is kept at {{model_guard_rejected}} for inspection. This slice's spec.md was already written, so remove {{feature_dir}} and run /appweaver adopt {{feature_name}} again."
+
+  # ═══════════ REVERSE API PLAN — the endpoints the slice publishes, AS-BUILT ═══
+  # The contract between the lanes, reversed before the backend plan exactly as `plan`
+  # authors it first: the backend plan then realises each endpoint, and the frontend plan
+  # binds to the operation ids written here. One template in every project — the kit's
+  # api-plan-template, whose endpoint block form is what the contract scripts read — so the
+  # code decides which endpoints there are and what they carry, never the document's shape.
+  - id: ctx_reverse_api
+    condition: "{{api_reverse}} == true"
+    action: build_context
+    context:
+      - { path: "{{api_plan}}" }                  # the scaffolded template = the fixed endpoint block form
+      - { path: "{{spec_file}}" }                 # the reversed spec = the US/FR ids each endpoint serves
+      - { path: "{{domain_model}}" }              # the ubiquitous language, and the BR-nnn an error answers to — READ, never written
+      - { path: "{{concept_path}}" }              # source_files + seam
+      - { path: .appweaver/DESIGN-FORMAT.md }     # the HLD contract, and The API plan in it
+      - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — the protocol the service publishes
+  - id: reverse_api
+    condition: "{{api_reverse}} == true"
+    action: agent_author
+    include_standards: true                        # the technical sticky set (reference only — the CODE wins)
+    tools: Read   # grounded in the CODE, which arrives as {{source_files}} paths
+    output_target: { type: file, path: "{{api_plan}}" }
+    task: |
+      Reverse-engineer the API PLAN of the feature '{{feature_name}}' (the target
+      api-plan.md in context — the kit's API plan template) FROM ITS CODE: every endpoint
+      the slice publishes for this feature. It is the API contract between the lanes — the
+      frontend plan binds to its operation ids, a script drafts it into api-draft.json,
+      analyze-slice checks the built service against it — and it is written BEFORE the
+      backend plan, which then realises each endpoint. READ the source files listed below;
+      the code is the SOURCE OF TRUTH.
+      Rules:
+      - DESCRIBE THE API AS-BUILT, quirks included: each endpoint's route, verb,
+        parameters, request and response fields, status codes and error bodies exactly as
+        the code serves them, with the field names as they appear on the wire. Never tidy
+        a route, rename a field or add a status the code does not return.
+      - THE FEATURE'S SCOPE. {{operations_note}} An endpoint that serves only a sibling
+        feature's operation is that feature's and is left out, even though its file is
+        listed; a read both features call is this feature's too.
+      - KEEP THE TEMPLATE'S FORM EXACTLY: one block per endpoint under "## Endpoints" — the
+        heading `### `VERB /route` — purpose · Serves …` citing the reversed spec's US/FR
+        ids, then **Operation id**, **Auth**, **Request**, **Success**, the **Errors** table
+        and **Maps to**. The contract scripts read exactly this form; an endpoint written
+        as a table row or in prose reaches neither api-draft.json nor the frontend.
+      - EVERY SHAPE IS `{ field: type }` in conceptual types (string, int, decimal, bool,
+        enum(A|B), list<T>, id<T>, money, date, datetime), never the code's own types. A
+        shape in prose reaches the frontend's client untyped.
+      - THE OPERATION ID is the id the code publishes the endpoint under, spelled exactly as
+        the code spells it; the boundary map records each operation's published id where
+        the code declares one (the scope line above). Where the code publishes none, write
+        `—` and say so in the block — never invent one: the service's as-built API document
+        would not carry it, so the frontend would bind to an id the service does not
+        answer, and analyze-slice would report it.
+      - **Maps to** names the code's own unit that serves the endpoint — its handler,
+        use-case or service operation — by the name the code gives it; the backend plan,
+        reversed next from the same code, realises it under that name.
+      - THE ERROR CONTRACT is what the code returns: one row per failure it actually
+        produces, with its status, when it is returned and its body shape. An error the
+        code never produces is not written.
+      - Under "## Requests from the frontend lane" write `None`: a frontend reversed from
+        the same code binds only to what the service already serves, so no request is
+        open yet.
+      - A SERVICE THAT PUBLISHES ANOTHER PROTOCOL (messages, remote procedures) states each
+        operation in the same block form, headed by the code's own name for it.
+      - Write `None` under "## Endpoints" when the slice publishes no endpoint.
+      - TECHNOLOGY-AGNOSTIC: protocol level only — no controller code, framework
+        attributes, serializer settings or language types.
+      - Add `origin: reverse-engineered` near the Version field. This is v1.0: write the
+        first Change History row.
+
       Source files to read (the slice's code): {{source_files}}
 
   # ═══════════ REVERSE BACKEND PLAN — from the SPEC + MODEL + CODE, AS-BUILT ═══
@@ -744,16 +982,19 @@ workflow:
   # backend-plan.md IS onboard's code-derived `design-template` override — its §2
   # component sections follow the code's own folders/modules, not a fixed layering.
   - id: ctx_reverse_plan
+    condition: "{{svc_lane}} == true"
     action: build_context
     context:
       - { path: "{{backend_plan}}" }              # the scaffolded code-derived template = structure + embedded guidance
       - { path: "{{spec_file}}" }                 # the reversed spec = WHAT the slice must do
+      - { path: "{{api_plan}}", optional: true }  # the reversed API = the endpoints this plan realises — absent where the scaffold refused
       - { path: "{{domain_model}}" }              # the reversed model = what the domain IS — READ, never written here
       - { path: "{{concept_path}}" }              # source_files + seam (structure hints)
       - { path: .appweaver/DESIGN-FORMAT.md }        # the HLD contract (see its Brownfield variant note)
       - { path: "{{bundle_dir}}/architecture/overview.md", optional: true } # the as-built architecture (inventory) — cite, don't re-derive
       - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain
   - id: reverse_plan
+    condition: "{{svc_lane}} == true"
     action: agent_author
     include_standards: true                        # the technical/architecture sticky set (reference only — the CODE wins)
     tools: Read   # grounded in the CODE, which arrives as {{source_files}} paths
@@ -798,6 +1039,7 @@ workflow:
         the EXTERNAL INTEGRATIONS table (heading contains "Integration") realising the
         spec's IC-. Realise CN- (structural → §1.2 invariants/events; retention/audit →
         §2 persistence / §3 cross-cutting), DC- (§3 + projection surface).
+      - {{be_api_rule}}
       - AS-BUILT DEBT, not architecture drift. §6 records ONLY debt the CODE ITSELF
         evidences — stubs/no-ops, dead or duplicate code, torn seams (shared table/
         transaction), TODOs, hard-coded values. The code being organised differently
@@ -816,8 +1058,9 @@ workflow:
   # ═══════ REVERSE UI DESIGN — the LANE's half, from the UI code, AS-BUILT ═══
   # Runs only where this slice HAS a surface (ui_lane). The service design above is
   # NOT its parent: backend-plan.md realises the spec's FR/BR/CN-, frontend-plan.md
-  # realises the spec's UX- and the user stories' interaction, and it CONSUMES the backend
-  # plan's contracts rather than restating them. Both are in context for exactly that reason.
+  # realises the spec's UX- and the user stories' interaction, and it CONSUMES the API
+  # plan's contracts rather than restating them. The spec and the API plan are in context
+  # for exactly that reason; the backend plan, the service's internals, is not.
   # THE FRONTEND'S RULES REPLACE THE BACKEND'S before the lane's plan is authored — the
   # swap the forward `plan` makes at the same boundary. Sticky standards only accumulate,
   # so without it the UI plan was authored under the service rule set and none of the
@@ -835,7 +1078,7 @@ workflow:
     context:
       - { path: "{{frontend_plan}}" }             # the scaffolded code-derived lane template = structure + embedded guidance
       - { path: "{{spec_file}}" }                 # the reversed spec — UX- + the user stories this surface serves
-      - { path: "{{backend_plan}}" }              # the backend plan — the contracts the UI consumes, never re-specified here
+      - { path: "{{api_read}}", optional: true }  # the API plan — the contracts the UI consumes, never re-specified here; absent with no service lane
       - { path: "{{domain_model}}", optional: true }  # the ubiquitous language labels and states must use — READ, never written
       - { path: .appweaver/memory/constitution.ui.md, optional: true }              # the lane's UX-* base, reversed by onboard from this same UI
       - { path: "{{bundle_dir}}/architecture/frontend.md", optional: true }       # the as-built UI architecture + the SHARED surface no slice owns
@@ -861,11 +1104,20 @@ workflow:
         operation — typically that feature's own UI folder — is that feature's. Where this
         feature's screen hosts it, cite it as the sibling's; never plan it here.
       - STAY IN THE LANE. Realise the spec's Experience Standards (UX-) and the
-        interaction its User Stories imply. The backend plan (in context) supplies
-        the CONTRACTS this surface consumes — cite them; do NOT restate, re-derive or
-        contradict them, and introduce no server-side behaviour here. Where the domain
+        interaction its User Stories imply. The API plan (in context — api-plan.md, or the
+        backend plan where this feature's endpoints stayed in it) supplies the CONTRACTS
+        this surface consumes — cite them; do NOT restate, re-derive or contradict them,
+        and introduce no server-side behaviour here. With no API plan in context the
+        service is outside this repo: bind against the routes the UI code calls and the
+        spec's IC-, as an external contract. Where the domain
         model is in context, use its UBIQUITOUS LANGUAGE exactly in labels, states and
         messages, and cite BR-nnn rather than restating a rule.
+      - CONTRACT BINDING CITES OPERATION IDS. Each row of the Contract Binding table names,
+        in its Operation id column, the **Operation id** the API plan gives the endpoint
+        the UI code calls — `—` where the API plan records none. The id is how
+        implement finds the endpoint, and how a later change that alters or removes it is
+        reported to this lane. The "Contract deltas needed" table reads `None`: the UI calls
+        only what the service already serves.
       - STRUCTURE FOLLOWS THE UI CODE. Fill each section from the lane's real shape —
         its actual routes and screens, its own composition axes (however it groups
         components), where client state and server data-fetching really live, its
@@ -890,7 +1142,8 @@ workflow:
     context:
       - { path: .appweaver/templates/source-map-template.md }   # the sidecar structure
       - { path: "{{spec_file}}" }
-      - { path: "{{backend_plan}}" }
+      - { path: "{{backend_plan}}", optional: true }    # the service lane's plan, where this slice has one
+      - { path: "{{api_plan}}", optional: true }        # the endpoints the slice publishes, where it has a service half
       - { path: "{{frontend_plan}}", optional: true }   # the lane's design, where this slice has one
       - { path: "{{concept_path}}" }              # both file lists to map
   - id: source_map
@@ -904,7 +1157,8 @@ workflow:
       spine — it keeps spec.md / backend-plan.md clean while recording provenance here.
       - One row per legacy artefact in the bundle concept's `source_files` (read
         them under {{module_dir}}): map each to the spec ids (FR/BR/US/CN/DC/IC)
-        and the backend-plan element (§/name) that now describe it, with CONFIDENCE
+        and the backend-plan element (§/name) that now describe it — and, for a file
+        that publishes an endpoint, its `VERB /route` block in api-plan.md — with CONFIDENCE
         (certain | inferred). EVERY source file MUST appear — the Fidelity gate
         checks full coverage both ways.
       - THE CONCEPT IS THE AGGREGATE'S ('{{aggregate_primary}}') and lists every feature's
@@ -945,7 +1199,8 @@ workflow:
     context:
       - "{{spec_file}}"
       - "{{domain_model}}"
-      - "{{backend_plan}}"
+      - { path: "{{backend_plan}}", optional: true }    # the service lane's plan, where this slice has one
+      - { path: "{{api_plan}}", optional: true }        # the endpoints it publishes, where this slice has a service half
       - { path: "{{frontend_plan}}", optional: true }   # the lane's plan, where this slice has one
       - "{{feature_dir}}/source-map.md"
       - "{{concept_path}}"
@@ -960,7 +1215,10 @@ workflow:
       {{module_dir}}). Where frontend-plan.md is in context, it is judged the same way
       against the slice's UI files ({{ui_source_files}}) — a screen, state store or
       route it describes that the UI code does not have is a fabricated-plan, and a
-      UI file with no home in the source-map is unmapped-code. Classify findings:
+      UI file with no home in the source-map is unmapped-code. Where api-plan.md is in
+      context, it is judged against the service code the same way: an endpoint the code
+      does not serve, a field or status it does not have, or an operation id the code does
+      not publish is a fabricated-plan. Classify findings:
       - BLOCKING (structural — set ok=false if any):
         (1) unmapped-code: a source file with NO home in the source-map — one recorded
             there as `sibling: <Feature>` has a home;
@@ -1006,7 +1264,13 @@ workflow:
     condition: "{{report_needed}} == true"
     action: agent_author
     include_standards: false
-    context: ["{{spec_file}}", "{{domain_model}}", "{{backend_plan}}", "{{feature_dir}}/source-map.md"]
+    context:
+      - "{{spec_file}}"
+      - "{{domain_model}}"
+      - { path: "{{backend_plan}}", optional: true }
+      - { path: "{{api_plan}}", optional: true }
+      - { path: "{{frontend_plan}}", optional: true }
+      - "{{feature_dir}}/source-map.md"
     output_target: { type: file, path: "{{feature_dir}}/adopt-review-report.md" }
     task: |
       Write an Adopt Review report (the target) for the feature '{{feature_name}}' (acting on {{aggregates_csv}}) —
@@ -1014,8 +1278,10 @@ workflow:
       - "# Adopt Review — {{feature_name}}" + today's date + "origin: reverse-engineered".
       - "verdict:" line — "BLOCKING ✗ · <n>" if blocking gaps exist, else "REVIEW ○ · <m> item(s)".
       - "## Blocking gaps" (if any): table | # | kind | artefact | detail | — MUST be
-        resolved before the slice is trustworthy (fix by re-reading the code / refining
-        spec+design, then re-run adopt-review or re-adopt).
+        resolved before the slice is trustworthy, one of two ways: re-adopt — remove
+        {{feature_dir}} and run /appweaver adopt {{feature_name}} again, which reverses
+        the documents afresh from the code, so edits made to them by hand are not kept —
+        or correct the documents by hand and keep them.
         Blocking gaps: {{blocking_gaps}}
       - "## Review items" (close out of band): table | # | kind | where | confirm |.
         These are inferred-vs-certain calls, as-built quirks, and missing-invariant
@@ -1034,7 +1300,7 @@ workflow:
     action: verify_context
     require_true: fidelity_ok
     on_false: stop
-    on_false_message: "Fidelity FAILED for {{feature_name}} — the reversed documents do not match the code (blocking gaps: {{blocking_gaps}}). See {{feature_dir}}/adopt-review-report.md. Fix the unmapped code / remove fabricated items (re-read the source, refine spec.md, {{domain_model}}, backend-plan.md and source-map.md), then re-run /appweaver adopt (after removing the dir) or resolve out of band. A `fabricated-model` gap means the reverse gave this slice structure its code does not have — an entity, a boundary, a lifecycle state or a BR-nnn nothing enforces; the fix is to record the domain as thin as the code really is, never to leave it flattering. A `foreign-operation` gap means a document claims an operation the boundary map gives only to another feature; remove it here — it belongs to that feature's adopt."
+    on_false_message: "Fidelity FAILED for {{feature_name}} — the reversed documents do not match the code (blocking gaps: {{blocking_gaps}}). See {{feature_dir}}/adopt-review-report.md. Resolve it one of two ways. RE-ADOPT: remove {{feature_dir}} and run /appweaver adopt {{feature_name}} again; the documents are reversed afresh from the code, so edits made to them first are not kept. Removing the folder leaves what this run added to {{domain_model}} (git diff shows it), and a re-adopt extends it, so remove that first. CORRECT BY HAND: re-read the source and refine spec.md, {{domain_model}}, the API plan and lane plans this slice has (API: {{api_plan}}; backend: {{backend_plan}}; frontend: {{frontend_plan}}) and source-map.md — map the unmapped code, remove what is fabricated. This run stopped before it completed the OKF concept {{aggregate_primary}}, recorded cross-slice edges and drew the API draft, so on this path the concept and the edges stay as onboard left them and the slice has no api-draft.json until /appweaver analyze-plan draws it. A `fabricated-model` gap means the reverse gave this slice structure its code does not have — an entity, a boundary, a lifecycle state or a BR-nnn nothing enforces; the fix is to record the domain as thin as the code really is, never to leave it flattering. A `foreign-operation` gap means a document claims an operation the boundary map gives only to another feature; remove it here — it belongs to that feature's adopt."
 
   # ═══════════ OKF CONCEPT — COMPLETE the shallow scan concept (deep reverse) ═══
   # onboard wrote this aggregate's OKF concept SHALLOW (a discovery stub — enough to pick the
@@ -1051,7 +1317,9 @@ workflow:
       - { path: "{{concept_path}}" }                          # the shallow onboard concept to complete
       - { path: "{{spec_file}}" }                             # the deep reversed spec (entities, US, BR/CN/DC/IC)
       - { path: "{{domain_model}}" }                           # the deep reversed model (entities, boundary, invariants)
-      - { path: "{{backend_plan}}" }                            # the deep reversed plan (components, ports, integrations)
+      - { path: "{{backend_plan}}", optional: true }            # the deep reversed service plan (components, ports, integrations), where the slice has one
+      - { path: "{{api_plan}}", optional: true }                # the deep reversed API (the endpoints it publishes), where the slice has a service half
+      - { path: "{{frontend_plan}}", optional: true }           # the deep reversed UI plan, where the slice has one
       - { path: "{{feature_dir}}/source-map.md" }             # the source anchor (files, seam, quirks)
       - { path: .appweaver/templates/okf-concept-template.md }  # OKF v0.1 format authority
   - id: complete_concept
@@ -1063,8 +1331,8 @@ workflow:
       COMPLETE the OKF concept of the aggregate '{{aggregate_primary}}' at {{concept_path}} —
       the aggregate this run adopted the feature '{{feature_name}}' over. onboard wrote it
       SHALLOW (a discovery stub from the whole-repo scan). The deep reverse has now
-      produced a TRUSTWORTHY spec.md + domain-model.md + backend-plan.md + source-map.md (in
-      context); deepen the
+      produced a TRUSTWORTHY spec.md + domain-model.md + api-plan.md + backend-plan.md +
+      source-map.md (in context, each the slice has); deepen the
       concept to match and LINK those artifacts. Follow the OKF concept template in context.
       THE CONCEPT IS THE AGGREGATE'S, NOT THE FEATURE'S. Where its `features:` names more
       than one feature, another feature's adopt may already have deepened it, and nothing
@@ -1076,8 +1344,9 @@ workflow:
         the authority on them; correct any drift the shallow scan got wrong (the deep docs
         win). A sibling capability's commands and endpoints stay where they are.
       - LINK the deep artifacts: add bundle links to {{feature_dir}}/spec.md,
-        backend-plan.md, source-map.md and the context's domain-model.md so the concept
-        points at the deep truth. Keep every link another feature's adopt added.
+        backend-plan.md, api-plan.md, source-map.md and the context's domain-model.md (each
+        the slice has) so the concept points at the deep truth. Keep every link another
+        feature's adopt added.
       - UNION `source_files` with the source-map's mapped files (grouped by the code's OWN
         folders, per OKF) — never drop a file already listed, which may be a sibling
         capability's. The boundary map was drawn at the baseline commit, whose time is
@@ -1109,6 +1378,7 @@ workflow:
   #     reconcile-on-write helper as forward implement, stamped origin reverse-engineered,
   #     additive to the inventory bundle. Runs only after fidelity passes.
   - id: xref_record
+    condition: "{{svc_lane}} == true"   # edges are read off the service plan, as forward implement records them
     action: execute_script
     script: { ref: xref }
     subcommand: record
@@ -1117,6 +1387,37 @@ workflow:
       - { name: xref_wrote,      from: "$.wrote" }
       - { name: xref_edge_count, from: "$.edge_count" }
 
+  # 3c. THE API DRAFT — api-draft.json beside the plans, drawn by script from the API plan just
+  #     reversed (the backend plan, where its endpoints stayed in it): the API contract the
+  #     frontend lane's combined document reads and analyze-slice checks the built service
+  #     against. Drawn here, after fidelity passed, so the adopted slice is in the combined
+  #     document from the start rather than only once plan or analyze-plan next runs for it.
+  #     Advisory — a plan the script cannot read leaves the run going; a shape it cannot type
+  #     is reported, because the frontend's client gets that data untyped.
+  - id: contract_draft
+    condition: "{{svc_lane}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: contract-draft
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: draft_path,        from: "$.path" }
+      - { name: draft_plan,        from: "$.plan" }
+      - { name: draft_ops,         from: "$.operations" }
+      - { name: draft_unread,      from: "$.unread_count" }
+      - { name: draft_unread_text, from: "$.unread_text" }
+  - id: draft_unread_flag
+    condition: "{{draft_unread}} != 0"
+    action: set
+    vars: { draft_clean: "false" }
+  - id: warn_draft_unread
+    condition: "{{svc_lane}} == true"
+    action: verify_context
+    require_true: draft_clean
+    on_false: continue
+    on_false_message: "API DRAFT — {{draft_unread}} endpoint shape(s) in {{draft_plan}} are not written as `{ field: type }`, so the frontend's client gets that data untyped: {{draft_unread_text}}. Write each request and response the way the API plan template's endpoint block does, with the fields the code puts on the wire, then run /appweaver analyze-plan, which redraws the draft."
+
   # ═══════════ GOVERNANCE RECONCILE — upgrade onboard's PROVISIONAL scaffold ═══
   # ⏸ HELD 2026-07-29: every step in this block is gated on `reconcile_governance`
   #   (default "false"), so adopt currently does NOT touch the constitution halves
@@ -1327,13 +1628,17 @@ workflow:
 outputs:
   feature_dir: "{{feature_dir}}"
   spec_file: "{{spec_file}}"
+  api_plan: "{{api_plan}}"             # empty where this slice has no service half, or its backend plan keeps the endpoints
+  api_draft: "{{draft_path}}"          # api-draft.json drawn from it — empty where the slice has no service half or publishes no endpoint
+  api_draft_operations: "{{draft_ops}}"
   backend_plan: "{{backend_plan}}"
   frontend_plan: "{{frontend_plan}}"   # empty where this slice has no UI half
   domain_model: "{{domain_model}}"     # the CONTEXT's, shared — this run ADDED an aggregate section to it
   bounded_context: "{{context}}"
+  svc_lane: "{{svc_lane}}"
   ui_lane: "{{ui_lane}}"
   ui_count: "{{ui_count}}"
-  feature_lanes: "{{feature_lanes}}"   # empty = every declared lane; [backend] = a service-only slice in a repo with a frontend
+  feature_lanes: "{{feature_lanes}}"   # empty = every declared lane; [backend] = a service-only slice in a repo with a frontend; [frontend] = a UI-only slice in a repo with a service
   operations: "{{operations_csv}}"     # this feature's operations, from the boundary map
   baseline_commit: "{{baseline_commit}}"
   source_map: "{{feature_dir}}/source-map.md"
@@ -1352,4 +1657,4 @@ outputs:
   composed_file: "{{composed_file}}"
   technical_reconcile_ok: "{{technical_ok}}"
   domain_reconcile_ok: "{{domain_ok}}"
-  next: "Adopted {{feature_name}} (spec.md + backend-plan.md + source-map.md, v1.0) and wrote {{aggregate_sections}} — the model section(s) for the aggregate(s) it acts on, resolved from the {{aggregate_source}} — in the bounded context `{{context}}`'s shared {{domain_model}}. The spec cites BR-nnn by id, the model carries their text, so this slice is checkable by the same gates as a greenfield one and analyze-plan's check 4 now has a model to check against. A section another feature over the same aggregate wrote first was EXTENDED, never duplicated; every other section is untouched. COMPLETED the OKF concept of {{aggregate_primary}} (deepened + linked the deep artifacts; {{xref_edge_count}} cross-slice edge(s) recorded). UI HALF: ui_lane={{ui_lane}} — where it is true this slice also has frontend-plan.md, reversed from the {{ui_count}} UI file(s) the feature map attributes to it; where it is false the repo declared no frontend lane, or this aggregate owns no part of its surface, and a service-only adoption is the correct outcome rather than a gap. In the second case, where a frontend lane IS declared, the feature records lanes=[backend] in its active_version.json (feature_lanes shows it), so plan and the analyze gates treat the frontend lane as absent for THIS feature; run `aw-spec-actions feature-lanes --clear` if it later gains a UI. The SHARED UI surface (app shell, layout, design system) belongs to no slice and stays in {{bundle_dir}}/architecture/frontend.md. NOTE — governance reconcile is currently HELD (reconcile_governance=false): this run did NOT modify the constitution halves or the guardrails/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in {{feature_dir}}/adopt-review-report.md out of band. The slice is now a NORMAL feature: refine via /appweaver analyze-plan, then drive every change through the CR delta loop (/appweaver specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta). If a change edits untested legacy behaviour with blast radius, characterize just that surface first (optional on-touch fence). To restore governance reconcile, set reconcile_governance to 'true' in the workflow vars."
+  next: "Adopted {{feature_name}} (spec.md, source-map.md, the API plan and the lane plans this slice has — API: {{api_plan}}; backend: {{backend_plan}}; frontend: {{frontend_plan}} — v1.0) and wrote {{aggregate_sections}} — the model section(s) for the aggregate(s) it acts on, resolved from the {{aggregate_source}} — in the bounded context `{{context}}`'s shared {{domain_model}}. The spec cites BR-nnn by id, the model carries their text, so this slice is checkable by the same gates as a greenfield one and analyze-plan's check 4 now has a model to check against. A section another feature over the same aggregate wrote first was EXTENDED, never duplicated; every other section is untouched. COMPLETED the OKF concept of {{aggregate_primary}} (deepened + linked the deep artifacts; {{xref_edge_count}} cross-slice edge(s) recorded). API DRAFT: {{draft_ops}} operation(s) drawn from the API plan into api-draft.json beside it, the API the frontend lane binds to and analyze-slice checks the service against (0 where the slice has no service half). UI HALF: ui_lane={{ui_lane}} — where it is true this slice also has frontend-plan.md, reversed from the {{ui_count}} UI file(s) the feature map attributes to it; where it is false the repo declared no frontend lane, or this aggregate owns no part of its surface, and a service-only adoption is the correct outcome rather than a gap. In the second case, where a frontend lane IS declared, the feature records lanes=[backend] in its active_version.json (feature_lanes shows it), so plan and the analyze gates treat the frontend lane as absent for THIS feature; run `aw-spec-actions feature-lanes --clear` if it later gains a UI. SERVICE HALF: svc_lane={{svc_lane}} — false where the repo declares no backend lane (a frontend-only project: no backend plan, no cross-slice edges, and the model was read from the UI code) or this slice has no service code; in the second case, where a frontend lane carries it, the feature records lanes=[frontend] the same way. The SHARED UI surface (app shell, layout, design system) belongs to no slice and stays in {{bundle_dir}}/architecture/frontend.md. NOTE — governance reconcile is currently HELD (reconcile_governance=false): this run did NOT modify the constitution halves or the guardrails/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in {{feature_dir}}/adopt-review-report.md out of band. The slice is now a NORMAL feature: refine via /appweaver analyze-plan, then drive every change through the CR delta loop (/appweaver specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta). If a change edits untested legacy behaviour with blast radius, characterize just that surface first (optional on-touch fence). To restore governance reconcile, set reconcile_governance to 'true' in the workflow vars."