aw-spec-cli 0.1.31 → 0.1.33

package/assets/.appweaver/DESIGN-FORMAT.md

@@ -82,11 +82,18 @@ same traceability spine and the two deferral ledgers — with **one difference t
   are **derived from the code's own organisation** (its folders / projects / modules)
   rather than the fixed Domain/Application/API/Infrastructure four. A component the
   code has that fits no textbook layer (a UI tier, a worker, a host project) gets its
-  own section; a layer the code lacks does not appear. Two neutral anchors are kept
+  own section; a layer the code lacks does not appear. Three neutral anchors are kept
   because every system has them and the tooling keys on them: **§1 is the domain/data
-  model** (the cross-reference tool reads it for `<Other>Id` reference edges) and one
+  model** (the cross-reference tool reads it for `<Other>Id` reference edges), one
   **§2 subsection is the External Integrations table** (matched by heading keyword, so
-  `aw-xref` extracts contract edges from either layout). The `debt` ledger records
+  `aw-xref` extracts contract edges from either layout), and **each published endpoint
+  is an endpoint block** — the greenfield §3 form, `#### `VERB /route`` with its
+  **Operation id**, followed by the "Requests from the frontend lane" table — inside
+  whichever §2 axis publishes it. The contract scripts read exactly that form: the API
+  draft is written from the headings, and the request ledger between the two lanes reads
+  the operation ids and the table. An endpoint the code already serves keeps the id it
+  publishes; where it publishes none the plan writes `—` and records a §5 assumption,
+  never an invented id. The `debt` ledger records
   only debt the **code itself** evidences (stubs, dead code, torn seams) — being
   organised unlike a reference architecture is **not** debt, it is the as-built shape;
   migrating toward a target is a separate modernization decision.

package/assets/.appweaver/STACK-PROFILES.md

@@ -113,6 +113,14 @@ project it does not exist yet — the whole point of declaring `backend/` on day
 `build`, `run`, and before `onboard` reverse-engineers a codebase out of it. That split is what lets one file serve a project with no code yet and a project that is
 nothing but code.
 
+A lane can also be declared before it is built on a project that has code — a new front end
+planned beside an existing service, or the reverse. `inventory` and `onboard` read code, so
+they pass `--allow-missing-root` and read the lanes whose folders exist (`kinds_on_disk`): a
+declared lane whose lane root folder is not there yet is read and governed as absent, and
+named in a warning and in the proposal's Scanned line. Its governance is the developer's to
+provide before the forward pipeline builds it. Both stop, with each missing folder named
+(`missing_roots`), only when no declared lane's folder exists.
+
 Two failure classes, deliberately distinguished:
 
 - **MISSING** — the phase needs a lane of this kind and none is declared. Reported only for
@@ -691,7 +699,7 @@ implementation and the twins cannot drift.
 | `contract-check --plan p [--doc d]` | the operation ids a frontend plan cites (its §5 `Operation id` column, or a delta plan's `Contract Binding` rows; never the request table) against the document's `operationId`s — by script, no model. `drafted[]` names the cited ids that are only draft operations |
 | `contract-impact --delta-backend p --frontend-plan p [--delta-frontend p]` | the operations a change's service delta marks `changed` or `removed` in its "Contract deltas for the frontend lane" table that the frontend master plan binds to, and which of them the change's frontend delta plan does not name (`unaddressed[]`) — `analyze-plan-delta`'s warning. By script, no model |
 | `lane-resolve [--kind k] [--id lane] [--feature-dir p]` | read; exit 0 always. `exists` reports the file, `declared` reports the lanes — the shipped-but-unfilled seed is `exists:true, declared:false`. Returns the matched lane **and** both kinds flattened — `backend_source_path`, `frontend_root_exists`, `backend_build` … — so a workflow binds one variable instead of calling twice — and the working-lane fields of §2a |
-| `lane-verify [--require backend\|frontend]… [--allow-missing-root] [--working-only] [--command phase]` | **the gate**: is the declaration usable for the phase about to run. Never writes, and **always exits 0** — the calling workflow's `verify_context` owns the stop, so the reason arrives as text. `--working-only` checks on disk only the working lanes' root folders and the required kinds (§2a) |
+| `lane-verify [--require backend\|frontend]… [--allow-missing-root] [--working-only] [--command phase]` | **the gate**: is the declaration usable for the phase about to run. Never writes, and **always exits 0** — the calling workflow's `verify_context` owns the stop, so the reason arrives as text. `--working-only` checks on disk only the working lanes' root folders and the required kinds (§2a). Whatever the flags, `kinds_on_disk[]` lists the kinds whose lane root folder exists and `missing_roots` the issue each declared lane without one raises when `--allow-missing-root` is not passed |
 | `lane-select [--lane backend\|frontend\|both] [--default] [--preselect text]` | read or write `.appweaver/lane.json` (§2a). No argument reads it and returns the `select_options[]` the declared stacks offer; `--lane` writes one of them; `--default` writes the default — `select-stack`'s call |
 | `cr-lanes [--cr-id id [--feature-dir p] [--stamp] [--set both\|backend\|frontend]]` | the lanes a change touches (§2a). No `--cr-id` returns the `select_options[]` the declared stacks offer, both first; with it, reads that change's `**Lanes**:` line — `lanes[]` is what it touches among the lanes declared now, every declared lane when nothing is recorded. `--set` writes an answer (a whole option line is accepted); `--stamp` alone writes every declared lane |
 | `slice-gate-stamp --cr-id id --lane backend\|frontend [--feature-dir p] [--tests-green b] [--tests-ran b] [--requirements-ok b] [--findings json]` | write one lane's `analyze-slice-delta` result to `changes/<id>/.aw-slice-gate.<lane>.json` (§2a): `verdict` `pass` when no test failed and the requirements are met, else `fail`, with `tests_ran` (false when the lane declares no test command, so nothing ran), the findings counts and the sha256 of the delta-spec and the lane's delta plan it was gated against. Findings that cannot be read are recorded as `null`, never as none |

package/assets/.appweaver/orchestrator/rev-templates/delta-design-template.skeleton.md

@@ -126,15 +126,19 @@ migration is needed (yes/no); any contract change other systems couple to.]
 
 ## Contract deltas for the frontend lane
 
-<!-- What this change adds to or alters in the service's PUBLISHED surface — the
-     only part of this document the frontend lane may bind against. `None` when
-     the surface is unchanged. Omit the section entirely where the code has no
-     frontend lane. The operation id is the endpoint's name in the published API
-     document; an endpoint that already has one keeps it. -->
+<!-- What this change adds to, alters in or removes from the service's PUBLISHED
+     surface — the only part of this document the frontend lane may bind against.
+     `None` when the surface is unchanged. Omit the section entirely where the code
+     has no frontend lane. The operation id is the endpoint's name in the published
+     API document; an endpoint that already has one keeps it. A `changed` or
+     `removed` row whose operation the frontend plan binds to is reported by
+     analyze-plan-delta (contract-impact reads the Operation id and Change
+     columns) until the frontend delta of this change — or a follow-up change —
+     carries the matching change. -->
 
 | Operation id | Contract | Change | Shape | Serves |
 |---|---|---|---|---|
-| `[OperationId]` | `[contract]` | [added / changed] | [request → response field shapes] | IC-[nnn] |
+| `[OperationId]` | `[contract]` | [added / changed / removed] | [request → response field shapes] | IC-[nnn] |
 
 ## Other open deltas
 

package/assets/.appweaver/orchestrator/rev-templates/design-template.skeleton.md

@@ -30,6 +30,13 @@
     • Exactly one §2 subsection's heading contains the word "Integration".
       `aw-xref` matches it by keyword to extract contract edges, which is what
       lets a derived layout and the greenfield layout be read by one tool.
+    • Each published endpoint is a `####` ENDPOINT BLOCK — the heading
+      `#### `[VERB] [/route]`` and its **Operation id** field — with the
+      "Requests from the frontend lane" table after the blocks, inside whichever
+      §2 axis publishes them. The contract scripts read exactly this form:
+      `contract-draft` drafts api-draft.json from the headings, and
+      `contract-requests` reads the operation ids and the table. The axis keeps
+      the project's own name; only the block form is fixed.
     • The traceability spine (§4) and both ledgers (§5 DA-n, §6 WA-n) survive
       every layout — the analyze gates read them.
     • The §0–§6 numbering itself: `plan`'s bootstrap_bf branch names those
@@ -169,9 +176,8 @@
      the titles are the code's answer — the slots below are illustrative
      positions, not a required set. In each: the components that live there,
      their behaviour in signature form, and the contracts they expose or
-     require. A component that PUBLISHES an endpoint names it with its route, verb
-     and operation id — the endpoint's name in the published API document, which
-     the frontend plan cites and implement looks the endpoint up by. -->
+     require. The endpoints the service PUBLISHES take the endpoint block form
+     shown in the axis below. -->
 
 ### 2.1 [PROJECT_STRUCTURAL_AXIS_NAME]
 
@@ -186,6 +192,50 @@
 
 <!-- … one per axis the code actually shows, then stop … -->
 
+### 2.[M] [AXIS_THAT_PUBLISHES_THE_ENDPOINTS]
+
+<!-- PINNED FORM, in whichever axis this project publishes its endpoints from. The
+     axis keeps the project's own name and its component table; what is fixed is
+     each endpoint's block below it and the requests table after the blocks,
+     because the contract scripts read exactly these: the `#### `VERB /route``
+     heading (contract-draft writes api-draft.json from it), the **Operation id**
+     field (the id the service serves, which the frontend plan binds to) and the
+     `| Request | Outcome |` table (contract-requests). A project that publishes no
+     endpoint omits both. -->
+
+| Component | Behaviour (signature) | Pre / Post / Raises | Serves |
+|---|---|---|---|
+| `[Component]` | `[operation](args) -> result` | [pre / post / raises] | FR-00X · US-Y |
+
+#### `[VERB] [/route]` — [purpose] · Serves US-Y · FR-00X
+
+- **Operation id**: `[OperationId]`  <!-- the endpoint's name in the published API document. An endpoint the code already serves keeps the id it publishes, spelled exactly as the code spells it; where it publishes none, write `—` and record a §5 DA-n saying so — never an invented id, which the service's exported document would not carry. A NEW endpoint takes an id unique across the service, and implement gives it exactly that. -->
+- **Auth**: [required role/scope, as enforced]
+- **Request**: `[path/query params]` + body `{ [field]: [type], … }`
+- **Success**: `2xx` → `{ [response shape] }`
+- **Errors** *(the error contract)*:
+
+  | Status | When | Body shape |
+  |---|---|---|
+  | [status] | [when it is returned] | [body shape] |
+
+- **Maps to**: `[Component]` (§2.n)
+
+#### Requests from the frontend lane
+
+<!-- THE ANSWERS to the frontend plan's "Contract deltas needed" table, one row
+     per RQ-n it raises. PUBLISH: add the endpoint above — under the proposed
+     operation id unless it clashes with one this service already uses — and name
+     the id here. DECLINE: say why in one line; a request the spec does not
+     support is declined as a spec gap for `specify`, never published on a guess.
+     Keep every answered row; write `None` instead of the table when the frontend
+     plan raises no request — always so for a plan reversed from code, whose
+     frontend binds only to what the service already serves. -->
+
+| Request | Outcome | Operation id | Why |
+|---|---|---|---|
+| RQ-[n] | published / declined | `[OperationId]` / — | [one line — required when declined] |
+
 ### 2.[N] External Integrations
 
 <!-- PINNED ANCHOR — the heading MUST contain the word "Integration"; the

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

@@ -71,7 +71,18 @@
 # =============================================================================
 
 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 — 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) 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.
+# 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 +98,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.3.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -128,8 +139,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: ""
@@ -424,14 +439,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 +509,69 @@ 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}}" }
+
+  - 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" }
+
   # 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
@@ -734,7 +804,8 @@ 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): {{source_files}}
+      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}}
 
   # ═══════════ REVERSE BACKEND PLAN — from the SPEC + MODEL + CODE, AS-BUILT ═══
   # Anchored to the reversed spec's ids (§4 Traceability → forward-compatible),
@@ -744,6 +815,7 @@ 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
@@ -754,6 +826,7 @@ workflow:
       - { 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 +871,21 @@ 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).
+      - EVERY ENDPOINT THIS FEATURE PUBLISHES IS AN ENDPOINT BLOCK, 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 exported API document would not carry it, so nothing could bind to 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. Later plans answer requests
+        there.
       - 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
@@ -835,7 +923,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: "{{backend_plan}}", optional: true }  # the backend 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
@@ -863,9 +951,17 @@ workflow:
       - 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
+        contradict them, and introduce no server-side behaviour here. With no backend 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** backend-plan.md gives the endpoint
+        the UI code calls — `—` where the backend 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 +986,7 @@ 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: "{{frontend_plan}}", optional: true }   # the lane's design, where this slice has one
       - { path: "{{concept_path}}" }              # both file lists to map
   - id: source_map
@@ -945,7 +1041,7 @@ workflow:
     context:
       - "{{spec_file}}"
       - "{{domain_model}}"
-      - "{{backend_plan}}"
+      - { path: "{{backend_plan}}", optional: true }    # the service lane's plan, where this slice has one
       - { path: "{{frontend_plan}}", optional: true }   # the lane's plan, where this slice has one
       - "{{feature_dir}}/source-map.md"
       - "{{concept_path}}"
@@ -1006,7 +1102,12 @@ 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: "{{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 +1115,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 +1137,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 lane plans this slice has (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}} and recorded cross-slice edges, so on this path both stay as onboard left them. 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 +1154,8 @@ 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: "{{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
@@ -1109,6 +1213,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
@@ -1331,9 +1436,10 @@ outputs:
   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 +1458,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 and the lane plans this slice has — 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). 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."