aw-spec-cli 0.1.33 → 0.1.35

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,13 @@
 # =============================================================================
 
 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 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.
+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
@@ -98,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.3.0
+version: 2.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -164,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
@@ -172,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
@@ -563,6 +592,21 @@ workflow:
     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
@@ -572,6 +616,22 @@ workflow:
     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
@@ -741,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
@@ -784,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).
@@ -807,6 +885,95 @@ workflow:
       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 ═══
   # Anchored to the reversed spec's ids (§4 Traceability → forward-compatible),
   # grounded in the code's ACTUAL structure, tech-agnostic. NO domain rule files (rule
@@ -820,6 +987,7 @@ workflow:
     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)
@@ -871,21 +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).
-      - 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.
+      - {{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
@@ -904,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
@@ -923,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}}", optional: true }  # the backend plan — the contracts the UI consumes, never re-specified here; absent with no service lane
+      - { 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
@@ -949,16 +1104,17 @@ 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. 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
+        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** backend-plan.md gives the endpoint
-        the UI code calls — `—` where the backend plan records none. The id is how
+        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.
@@ -987,6 +1143,7 @@ workflow:
       - { path: .appweaver/templates/source-map-template.md }   # the sidecar structure
       - { path: "{{spec_file}}" }
       - { 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
@@ -1000,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
@@ -1042,6 +1200,7 @@ workflow:
       - "{{spec_file}}"
       - "{{domain_model}}"
       - { 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}}"
@@ -1056,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;
@@ -1106,6 +1268,7 @@ workflow:
       - "{{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" }
@@ -1137,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. 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."
+    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
@@ -1155,6 +1318,7 @@ workflow:
       - { 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}}", 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
@@ -1167,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
@@ -1180,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
@@ -1222,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
@@ -1432,6 +1628,9 @@ 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
@@ -1458,4 +1657,4 @@ outputs:
   composed_file: "{{composed_file}}"
   technical_reconcile_ok: "{{technical_ok}}"
   domain_reconcile_ok: "{{domain_ok}}"
-  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."
+  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."