aw-spec-cli 0.1.32 → 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/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."

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

@@ -152,7 +152,7 @@
 
 name: aw-spec-onboard
 description: Onboard an existing codebase for brownfield DEVELOPMENT — a deterministic whole-repo scan produces a high-level OKF feature map (folders/concepts) PLUS the project-level governance scaffold (split constitution + guardrails/brf-<domain>/ with its DOMAIN rule files at domain/ + domain-rule-bindings + code-derived TECHNICAL rule files at service/ + tech-rule-bindings + activated domain), all provisional-from-scan. The first context authors that tier; every later context amends it additively from its own code (new rules, principles and map entries — never a rewrite, renumbering or deletion; a contradiction is recorded as a Divergence note), and a tier that does not exist yet, such as a lane declared after an earlier onboard, is authored in full. Naming an already-onboarded context re-runs that governance pass alone. Where the scan finds a frontend lane in the CODE, it also authors that lane's half — constitution.ui.md (UX-*) — and its code-derived rule files at brf-<domain>/frontend/, mapped under `## /aw-spec-ui-constitution`, `## /aw-spec-plan-frontend` and `## /aw-spec-implement-frontend`; a backend-only repo gets none of it. Every rule tier is reverse-engineered from the CODE alone (never a greenfield rule file), evidenced-only, and WIRED per-workflow so the whole forward pipeline AND adopt govern against THIS codebase — never a greenfield fallback. It also reverse-engineers the repo's own technical structure into a project-specific design + delta-design template pair, installed as the project template overrides, and — where the lane exists — the frontend lane's own pair from the UI source. Every authoring step is shaped by a NEUTRAL rev-templates skeleton; no greenfield constitution, rule file or document template is ever placed in context. Accepts an optional concerns list to look for (onboard decides which are actually present). Reads any declared lane whose folder exists, never writes one; a lane declared before it is built is governed as absent and its governance left to the developer. No migration content; never modifies source.
-version: 2.4.0
+version: 2.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -191,7 +191,7 @@ standards:
 vars:
   # The provenance stamp every generated file carries. It names THIS workflow's version,
   # so it moves with `version:` above — one value, never a literal repeated per prompt.
-  generated_by:   "aw-spec-onboard/2.4.0"
+  generated_by:   "aw-spec-onboard/2.5.0"
   bundle_present: "false"   # set by the scan (the bundle holds concepts); reported, gates nothing
   conformant:     "false"   # OKF conformance-gate driver
   pack_present:   "false"   # the project tier exists ⇒ repo_gov, so this context AMENDS it
@@ -332,11 +332,13 @@ workflow:
       - { name: bundle_dir,       from: "$.bundle_dir" }
       - { name: bundle_present,   from: "$.bundle_present" }
       - { name: bundle_md_count,  from: "$.bundle_md_count" }
-      # The frontend lane, as the CODE evidences it. `frontend_present` is true only
+      # The frontend lane, as the CODE evidences it. `frontend_evidenced` is true only
       # where a candidate root reached lane strength (a frontend build config, or a
       # real set of component/view files) — loose scripts and stylesheets under a
-      # wwwroot/ are reported in the substrate but are NOT a lane.
-      - { name: frontend_present,   from: "$.frontend_present" }
+      # wwwroot/ are reported in the substrate but are NOT a lane. It is the code's
+      # answer, kept apart from `frontend_present` (the UI rule tier exists, from
+      # pack_setup); which lanes this run governs is the declaration's answer, ui_lane.
+      - { name: frontend_evidenced, from: "$.frontend_present" }
       - { name: frontend_separable, from: "$.frontend_separable" }
       - { name: frontend_roots,     from: "$.frontend_roots" }
       - { name: frontend_root_count, from: "$.frontend_root_count" }
@@ -2303,6 +2305,16 @@ workflow:
         signature form + the ports/contracts. Keep exactly one subsection whose heading
         contains the word "Integration" (the External Integrations table — one port/adapter row
         per IC-): aw-xref matches it by keyword, so it is pinned regardless of layout.
+      - THE PUBLISHED SURFACE IS A PINNED FORM. In the §2 axis this project publishes its
+        endpoints from (titled with the project's own name for it), keep the skeleton's
+        endpoint block exactly — the heading `#### `[VERB] [/route]` — [purpose] · Serves …`,
+        then **Operation id**, Auth, Request, Success, the Errors table and Maps to — and the
+        `#### Requests from the frontend lane` table after the blocks. The contract scripts
+        read exactly this form: the API draft is written from the headings and the request
+        ledger between the lanes reads the operation ids and the table, so endpoints listed
+        in a table instead leave both empty. Keep the Operation id comment: an endpoint the
+        code already serves keeps the id it publishes, `—` with a §5 DA-n where it publishes
+        none, never an invented one. Omit both only where the code publishes no endpoint.
       - §3 Cross-Cutting Concerns — one row per concern THIS project's governance carries, read
         from the technical constitution (Serves = a spec id or a §5 DA-n). Do not import a
         standard concern list the constitution does not evidence.
@@ -2361,9 +2373,14 @@ workflow:
       the generated master template. Never name a layering — neither one you know nor one the
       master did not derive.
       - CARRY OVER the neutral parts of rev-templates/delta-design-template.skeleton.md (in
-        context): Change summary, Cross-section impact, Regression targets, New assumptions/
-        deviations (DA-n / WA-n), On merge — word for word: finalize-delta merges the spec and
-        the model, never this plan, which `plan main` re-derives. Keep behaviour technology-agnostic (signatures +
+        context): Change summary, Model changes this plan realises, Depends on, Cross-section
+        impact, Contract deltas for the frontend lane, Other open deltas, Regression targets,
+        New assumptions/deviations (DA-n / WA-n), On merge — word for word: finalize-delta
+        merges the spec and the model, never this plan, which `plan main` re-derives. Keep
+        the contract table's Operation id and Change columns and its added / changed /
+        removed values: analyze-plan-delta reads them to warn when a change alters or
+        removes an operation the frontend binds to. Omit that section only where the code
+        has no frontend lane. Keep behaviour technology-agnostic (signatures +
         contracts, no code); a shared element is MODIFIED in place, never duplicated; every
         changed element serves a spec id.
       - This aligns with the delta-plan module, which classifies "per the master's OWN

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

@@ -117,7 +117,7 @@
 
 name: aw-spec-plan
 description: "Author the feature's lane plans from the spec and the bounded context's domain model — backend-plan.md when a backend lane is declared, frontend-plan.md when a frontend lane is, both when both are. Lanes come from .appweaver/stacks.json, so one command covers backend-only, frontend-only and full-stack projects; the former separate design-ui command is folded in. It ASKS what it is planning, the way implement asks what it is building: the master (`main`), one of the OPEN CHANGES, or a new plan-only change for a refactor with no spec delta — the argument doubles as the answer, and the menu appears only once a master exists, so a first run bootstraps with no prompt. `main` on a feature that already has masters RE-DERIVES them from the merged spec.md + domain-model.md — the operation finalize-delta's contract assumes when it merges a change's spec and model halves and no lane plan — and is confirmed before it rewrites anything. A change instead gets delta-backend-plan.md / delta-frontend-plan.md inside changes/<CR-id>/ while the masters stay untouched, written against the effective model (the master model, the change's own model delta, and the pending model deltas of LOWER waves, which are its predecessors) and against the feature's real source files from its OKF concept. Master authoring is template-driven: the kit's templates by default, or the code-derived as-built structure when onboard installed an override. Authoring only — a master gates at analyze-plan; a change ships through the CR chain."
-version: 5.5.0
+version: 5.5.1
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -880,7 +880,11 @@ workflow:
       - NAME EVERY ENDPOINT with its route, verb and operation id — its name in the
         service's published API document, unique across the service. Where the code
         already gives the endpoint one, record THAT id exactly as the code spells it; the
-        frontend plan cites it and implement finds the endpoint by it.
+        frontend plan cites it and implement finds the endpoint by it. An endpoint the code
+        already serves under no id keeps `—`, with a §5 DA-n saying so — never an invented
+        id. Write each endpoint as the template's endpoint block — the heading
+        `#### `VERB /route` — …` with its **Operation id** field — never as a row in a table
+        of endpoints: the API draft and the request ledger between the lanes read that form.
       - ANSWER THE FRONTEND LANE'S CONTRACT REQUESTS. Still open in the frontend plan's
         "Contract deltas needed" table: {{req_backend_text}}. Answer each one in a
         "Requests from the frontend lane" table beside this feature's endpoints (| Request

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

@@ -16,7 +16,10 @@
 # still READ the other lane where they need it: a frontend plan binds to the backend
 # plan's published surface, which the backend developer owns. specify, finalize-delta and
 # close-delta do NOT follow it: the spec is written whole, from its rules and standards,
-# and a change merges and closes with whatever its lanes have delivered.
+# and a change merges and closes with whatever its lanes have delivered. Brownfield adopt
+# does not follow it either: it reverses a feature once, every half its code has, because
+# it cannot run a second time for the other lane, so the other lane's developer finds
+# their plan already written.
 #
 # THE OPTIONS COME FROM stacks.json. Both lanes declared → backend, frontend and both.
 # One lane declared → that lane only, picked without a question (there is nothing to
@@ -32,8 +35,8 @@
 # =============================================================================
 
 name: aw-spec-select-lane
-description: Choose the lane this developer works on — backend, frontend or both — and store it in .appweaver/lane.json, which is not committed, so each developer keeps their own. The options come from the stacks declared in .appweaver/stacks.json, all three when both lanes are declared and only the declared one otherwise. plan, analyze-plan, implement, build and analyze-slice then write only that lane while still reading the other; specify, finalize-delta and close-delta do not follow it. select-stack writes the default (every declared lane); run this to narrow it.
-version: 1.0.0
+description: Choose the lane this developer works on — backend, frontend or both — and store it in .appweaver/lane.json, which is not committed, so each developer keeps their own. The options come from the stacks declared in .appweaver/stacks.json, all three when both lanes are declared and only the declared one otherwise. plan, analyze-plan, implement, build and analyze-slice then write only that lane while still reading the other; specify, finalize-delta, close-delta and brownfield adopt do not follow it. select-stack writes the default (every declared lane); run this to narrow it.
+version: 1.0.1
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -100,5 +103,5 @@ outputs:
   working_lane: "{{working_lane}}"
   working_kinds: "{{working_kinds}}"
   lane_file: "{{lane_file}}"
-  note: "Working lane `{{working_lane}}` stored in {{lane_file}}. The file is not committed — it is this developer's choice, and another developer on the same repository keeps their own. From now on plan, analyze-plan, implement, build and analyze-slice write only the working lane: they plan it, gate it with its own receipt, generate it, compile it and test it. They still READ the other lane where they need it — a frontend plan binds to the operation ids the backend plan publishes. specify writes the whole spec whatever lane is chosen, and finalize-delta and close-delta merge and close a change with whatever its lanes have delivered. Re-running /appweaver select-stack resets the working lane to every declared lane."
+  note: "Working lane `{{working_lane}}` stored in {{lane_file}}. The file is not committed — it is this developer's choice, and another developer on the same repository keeps their own. From now on plan, analyze-plan, implement, build and analyze-slice write only the working lane: they plan it, gate it with its own receipt, generate it, compile it and test it. They still READ the other lane where they need it — a frontend plan binds to the operation ids the backend plan publishes. specify writes the whole spec whatever lane is chosen, and finalize-delta and close-delta merge and close a change with whatever its lanes have delivered. Brownfield adopt reverses a feature once, every half its code has, whatever lane is chosen, so the other lane's developer finds their plan already written. Re-running /appweaver select-stack resets the working lane to every declared lane."
   next: "Run the lane's flow on the active feature: /appweaver plan → analyze-plan → implement → build → analyze-slice. Switch lanes any time with /appweaver select-lane backend | frontend | both."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aw-spec-cli",
-  "version": "0.1.32",
+  "version": "0.1.33",
   "description": "AppWeaver Spec-Driven Development CLI - scaffolds projects with vertical slices, DDD, CQRS, and agent skills",
   "type": "module",
   "main": "dist/index.js",