aw-spec-cli 0.1.18 → 0.1.19

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

@@ -2,11 +2,21 @@
 # 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 + aligned design.md (+ 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
-# spec+design and generates code; adopt reads code and generates spec+design — equally
-# a reasoning step, stamped `origin: reverse-engineered` with per-item confidence.
+# 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
+# /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
+# per-item confidence.
+#
+# THE SPEC/MODEL SPLIT HOLDS ON THE REVERSE TOO (2026-09-14). The spec says what the slice
+# DOES and cites BR-nnn by id; the bounded context's domain-model.md says what the domain IS
+# and carries the aggregate root, its boundary, its entities and the TEXT of every invariant.
+# Adopt used to write the model INTO the spec as Key Entities / Business Rules, which left a
+# brownfield feature as the only kind the forward gates could not fully check: analyze-plan's
+# check 4 has nothing to check without a model, and implement generated with no authority on
+# the entity names it was using. The model is CONTEXT-level and shared, so a second adopted
+# slice ADDS its aggregate section and never touches the ones already there.
 #
 #   onboard → ADOPT <Feature> (JIT, one feature at a time) → [ forward / CR delta loop ]   ← you are here
 #
@@ -14,12 +24,15 @@
 # develop, never the whole codebase (that scale is what onboard's shallow feature map
 # avoids). A NEW feature (no existing code) is NOT adopted — it is authored straight
 # through the forward pipeline (/appweaver specify → plan → implement), which
-# onboard already made brownfield-ready (the code-derived design template is the
+# onboard already made brownfield-ready (the code-derived plan template is the
 # 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 + design.md are the very documents
-# the CR delta loop + forward pipeline consume unchanged. All brownfield provenance
+# 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.
+# 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
 # active_version.json (v1.0) so the CR loop works immediately after.
 #
@@ -56,7 +69,7 @@
 # =============================================================================
 
 name: aw-spec-adopt
-description: The JIT per-feature step of brownfield development — reverse-engineer ONE existing feature into a living spec.md + design.md (+ design.ui.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 design template), then COMPLETE its shallow OKF concept (deepen it to the reversed reality + link the deep artifacts) and record its cross-slice edges. Fidelity gate is spec/design vs code; the review is reported for out-of-band closure. 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 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. 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.
 # 1.5.0 — user_input is now OPTIONAL: adopt CONSUMES the ACTIVE feature (select-feature's
 #         .appweaver/feature.json) when no arg is passed, so onboard→select-feature→adopt needs
 #         no re-typing; an explicit <Feature> still selects directly (and wins). One coalesced
@@ -66,7 +79,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: 1.5.0
+version: 2.0.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -108,8 +121,22 @@ vars:
   ui_lane: "false"             # THIS slice reverses a UI half: a frontend lane is declared AND the slice owns UI files
   ui_count: "0"                # how many UI files the concept attributes to this aggregate (aw-inventory ui_source_files)
   ui_source_files: ""
-  ui_design_doc: ""
+  frontend_plan: ""
   ui_tpl_source: ""
+  # THE LANE PLANS, under the names the forward pipeline reads. A reversed slice is a
+  # NORMAL feature, so it carries backend-plan.md / frontend-plan.md like any other —
+  # plan-scaffold's backend/frontend lanes also MIGRATE a legacy design.md / design.ui.md
+  # 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 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
+  # together, so the model is never behind the spec that cites it.
+  context: ""
+  context_dir: ""
+  domain_model: ""
+  domain_model_exists: "false"
   spec_exists: "false"
   fidelity_ok: "false"
   rulemap_exists: "false"      # governance-present signal (onboard ran) — bound from resolve-domain
@@ -164,6 +191,35 @@ workflow:
     on_empty: stop
     on_empty_message: "No feature to adopt. Either run /appweaver select-feature first (pick the aggregate from the onboard feature map), then /appweaver adopt; or name it directly: /appweaver adopt <Feature>."
 
+  # WHICH BOUNDED CONTEXT THIS FEATURE LANDS IN, and a refusal to guess — the same gate
+  # select-feature carries, and needed here for the same reason: this stage also creates a
+  # feature directory. scope_ok is false in exactly one state, contexts exist and none is
+  # selected, and in that state set-feature resolves the target under a bare specs/ where
+  # it is outside every context. Worse on this path than on the forward one, because an
+  # adopted name comes from the reversed code rather than from a menu: adopting an
+  # aggregate that happens to share a name with an empty bounded context would write that
+  # context's own spec.md and orphan every feature meant to live inside it. A repo with no
+  # contexts at all passes, which keeps the flat brownfield layout working untouched.
+  - id: context_scope
+    action: execute_script
+    script: { ref: actions }
+    subcommand: list-contexts
+    outputs:
+      - { name: active_context, from: "$.active" }
+      - { name: context_count,  from: "$.count" }
+      - { name: scope_ok,       from: "$.scope_ok" }
+      - { name: scope_message,  from: "$.scope_message" }
+
+  - id: require_context_scope
+    action: verify_context
+    require_true: scope_ok
+    on_false: stop
+    on_false_message: >
+      {{scope_message}}
+      Adopting reverse-engineers one aggregate into a feature directory, so the context
+      that owns it has to be chosen before the directory is created — moving a feature
+      between contexts afterwards means re-specifying it in the new one.
+
   # Create-or-select the feature dir + persist it active (idempotent in the no-arg
   # path where it is already active; creates it in the explicit-arg path). set-feature
   # canonicalises to the PascalCase aggregate id → the single feature_name used below.
@@ -242,27 +298,57 @@ workflow:
     on_false_message: "No active governance for adopt to work against — run /appweaver onboard first. onboard establishes the PROJECT constitution + guardrails/projects/<project>/ rule set (provisional-from-scan) and activates it. Reversing '{{feature_name}}' without that scaffold would author the spec and design against no code-derived rules at all, and leave them with no governance home."
 
   # 2. Scaffold the living docs. The SPEC reuses the forward spec-template (it is
-  #    tech-agnostic WHAT/WHY — no architectural bias). The DESIGN scaffolds from the
+  #    tech-agnostic WHAT/WHY — no architectural bias). The BACKEND PLAN scaffolds from the
   #    DEFAULT `design-template` — which /appweaver onboard REPLACED with the repo's
   #    code-derived override (resolve_template Priority-1, reverse-engineered from the
-  #    code), so the reversed design's structural sections follow the code's own
+  #    code), so the reversed plan's structural sections follow the code's own
   #    architecture rather than a fixed greenfield layering, describing the system
-  #    as-built. (Falls back to the greenfield base if onboard has not run.) Both are
+  #    as-built. (Falls back to the greenfield base if onboard has not run.) The DOMAIN
+  #    MODEL scaffolds into the bounded CONTEXT, not the feature — it is shared. All are
   #    still normal forward docs (same identity + spine) that the CR delta loop consumes
   #    unchanged. Then init active_version.json (v1.0).
+  #
+  #    THE TEMPLATE IDENTIFIERS KEEP THE `design-template` SPELLING ON PURPOSE. The
+  #    DOCUMENTS moved to the plan names; the template NAMES did not, because a repo that
+  #    has already run onboard carries its code-derived override at
+  #    .appweaver/templates/overrides/design-template.md. Renaming the identifier would
+  #    make that file stop resolving and silently fall back to the kit's greenfield
+  #    template — imposing a four-layer structure on a codebase that chose another, which
+  #    is the exact failure require_ui_template below exists to prevent.
+  - id: context_paths
+    action: execute_script
+    script: { ref: actions }
+    subcommand: context-paths
+    outputs:
+      - { name: context,             from: "$.context" }
+      - { name: context_dir,         from: "$.context_dir" }
+      - { name: domain_model,        from: "$.domain_model" }
+      - { name: domain_model_exists, from: "$.domain_model_exists" }
+
   - id: scaffold_spec
     action: execute_script
     script: { ref: actions }
     subcommand: scaffold
     args: ["--feature-dir", "{{feature_dir}}", "--allow-existing"]
 
-  - id: scaffold_design
+  # Idempotent and non-destructive: a context whose model already exists (an earlier
+  # feature in it was adopted, or authored greenfield) keeps it, and the reverse below
+  # ADDS this aggregate's section rather than replacing the document.
+  - id: scaffold_model
     action: execute_script
     script: { ref: actions }
-    subcommand: design-scaffold
-    args: ["--feature-dir", "{{feature_dir}}"]   # default `design-template` = onboard's code-derived override (greenfield base if onboard has not run)
+    subcommand: model-scaffold
+    args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: design_doc, from: "$.design_doc" }
+      - { 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
@@ -299,18 +385,18 @@ workflow:
     condition: "{{ui_count}} == 0"
     vars: { ui_lane: "false" }
 
-  # Scaffold the LANE's design doc from ITS template pair (--lane ui resolves
-  # ui-design-template -> design.ui.md), the twin of scaffold_design above. onboard
-  # GENERATED that override from this repo's own UI source, so the reversed UI design
+  # 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
   # follows the code's real composition axes rather than a fixed screen taxonomy.
-  - id: scaffold_ui_design
+  - id: scaffold_ui_plan
     condition: "{{ui_lane}} == true"
     action: execute_script
     script: { ref: actions }
-    subcommand: design-scaffold
-    args: ["--feature-dir", "{{feature_dir}}", "--lane", "ui"]
+    subcommand: plan-scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--lane", "frontend"]
     outputs:
-      - { name: ui_design_doc, from: "$.design_doc" }
+      - { name: frontend_plan, from: "$.plan_doc" }
       - { name: ui_tpl_source, from: "$.template_source" }
       - { name: ui_tpl_override, from: "$.override_active" }
 
@@ -378,12 +464,15 @@ workflow:
         never a separate feature. Derive its Given/When/Then from the code's paths.
       - System Requirements in EARS (THE SYSTEM SHALL / WHEN / IF…THEN / WHILE /
         WHERE), each atomic + testable, derived from observed behaviour.
-      - Always-true invariants the code enforces → Business Rules (BR-n).
-      - MODEL IN THE TEMPLATE'S OWN VOCABULARY: a ubiquitous language, the
-        aggregate + its root, entities vs value objects, aggregate-owned
-        invariants — as domain MODEL, never as the language's own types.
-        Classify from what the code EXHIBITS. A distinction the code does not
-        draw is not a gap to fill in: record the model as-built, however thin.
+      - Always-true invariants the code enforces get stable BR-nnn ids, CITED here and
+        DEFINED in the domain model — see the next bullet.
+      - THE DOMAIN MODEL IS NOT THIS DOCUMENT'S. Fill "### Domain Model Reference" with
+        the aggregate's NAME and the ids of the invariants this spec relies on
+        (BR-nnn), and nothing more. Do NOT write the ubiquitous language, the aggregate
+        boundary, the entity/value-object split, the lifecycle states, or the TEXT of any
+        invariant: all of that lives in the bounded context's domain-model.md, which the
+        NEXT step reverses out of this same code, and several specs act on one aggregate
+        so a per-spec copy drifts. Cite by id; never restate.
       - DOMAIN LIFT — where the CODE enforces them, lift into the three sections
         (cite the source file): Constraints & NFRs (CN-, e.g. retention /
         immutability / append-only audit the code implements), Data Classification
@@ -419,31 +508,99 @@ workflow:
 
       Source files to read (the slice's code): {{source_files}}
 
-  # ═══════════ REVERSE DESIGN — from the reversed SPEC + CODE, AS-BUILT ═══════
+  # ══════════ REVERSE DOMAIN MODEL — the CONTEXT's structure, from the CODE ══════
+  # The greenfield split, applied to the reverse: the spec says what the system DOES, the
+  # bounded context's domain-model.md says what the domain IS — the aggregate root, its
+  # boundary, its entities and value objects, its lifecycle, and the TEXT of every BR-nnn
+  # the spec cites by id. Authored in the SAME run as the spec, exactly as `specify` does,
+  # so the model is never behind the spec that depends on it.
+  #
+  # THE MODEL IS THE CONTEXT'S, NOT THIS FEATURE'S. Every feature in the bounded context
+  # reads it, so adopting a second slice ADDS an aggregate section and must not touch the
+  # ones already there — a renumbered BR breaks every citation in every sibling spec,
+  # silently. The scaffold above is non-destructive for the same reason.
+  #
+  # THE CODE IS STILL THE ORACLE. No modelling rule file is loaded, for the reason the
+  # reversed spec loads none: a prescriptive standard states what a model OUGHT to be, and
+  # an anemic legacy slice must reverse as exactly that. A distinction the code does not
+  # draw is not a gap to fill in.
+  - id: ctx_reverse_model
+    action: build_context
+    context:
+      - { path: "{{domain_model}}" }              # the model — template on the context's first slice, POPULATED on a later one
+      - { 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 }
+  - id: reverse_model
+    action: agent_author
+    include_standards: false                       # the technical/arch sticky set is for the plans, never the model
+    tools: Read   # the structure is reversed from the CODE, which arrives as a path list
+    output_target: { type: file, path: "{{domain_model}}" }
+    task: |
+      Reverse-engineer the BOUNDED CONTEXT's DOMAIN MODEL (the target domain-model.md in
+      context) for the aggregate '{{feature_name}}', FROM ITS CODE. The reversed spec (in
+      context) names the aggregate and cites the invariant ids; this document DEFINES them.
+      READ the source files listed below — the code is the SOURCE OF TRUTH.
+
+      - ADD ONE `## Aggregate: <Name>` SECTION for this feature's aggregate: its boundary
+        (owns / references by id / out of scope), entities, value objects, domain events,
+        lifecycle states, and every always-true invariant the code enforces as a stable
+        BR-nnn with its RULE TEXT. The spec cites those ids and never restates them.
+      - IF THE MODEL ALREADY HAS CONTENT, this is the context's SECOND (or later) adopted
+        slice. ADD this aggregate as a new section and EXTEND the ubiquitous language. Do
+        NOT rewrite, renumber or "tidy" the aggregates 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.
+      - 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).
+        A slice that is anemic, or models nothing at all, reverses as exactly that — an
+        aggregate with no invariants is a true finding, and the fidelity gate scores an
+        invented one as a fabrication. Where the code's own grouping is unclear, record
+        what it shows and mark the item "(inferred)".
+      - CROSS-AGGREGATE REFERENCES BY ID ONLY, never a navigable link — where the code
+        does hold a direct object reference across a boundary, record the reference by id
+        here and leave the coupling fact to the source-map's Seam section.
+      - Fill "## Cross-Aggregate Invariants" (XBR-n) with rules the code enforces ACROSS
+        two or more aggregates — they belong to no single spec, which is why they can only
+        live here. "None (as of v1.0)" when the code shows none; never delete the section.
+      - Fill "## Context Map" with this context's relationships to others where the code
+        evidences them, or "None (as of v1.0)". Never delete the section.
+      - TECHNOLOGY-AGNOSTIC. No types, no persistence, no framework, no layering. WHERE an
+        invariant is ENFORCED is a plan concern and belongs in backend-plan.md.
+      - 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}}
+
+  # ═══════════ 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 files (rule
-  # partition). The scaffolded design.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_design
+  # grounded in the code's ACTUAL structure, tech-agnostic. NO domain rule files (rule
+  # partition) — the domain reaches this plan as the reversed spec's ids and as the
+  # context's domain model, which is READ here and never written. The scaffolded
+  # 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
     action: build_context
     context:
-      - { path: "{{design_doc}}" }                # the scaffolded code-derived template = structure + embedded guidance
-      - { path: "{{spec_file}}" }                 # the reversed spec = the ONLY domain input
+      - { path: "{{backend_plan}}" }              # the scaffolded code-derived template = structure + embedded guidance
+      - { path: "{{spec_file}}" }                 # the reversed spec = WHAT the slice must do
+      - { path: "{{domain_model}}" }              # the reversed model = what the domain IS — READ, never written here
       - { path: "{{concept_path}}" }              # source_files + seam (structure hints)
       - { path: .appweaver/DESIGN-FORMAT.md }        # the HLD contract (see its Brownfield variant note)
       - { path: "{{bundle_dir}}/architecture/overview.md", optional: true } # the as-built architecture (inventory) — cite, don't re-derive
       - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain
-  - id: reverse_design
+  - id: reverse_plan
     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
-    output_target: { type: file, path: "{{design_doc}}" }
+    output_target: { type: file, path: "{{backend_plan}}" }
     task: |
-      Reverse-engineer the MASTER high-level design (the target design.md in
-      context — it is the BROWNFIELD design template) — the tech-agnostic HLD that
-      MEDIATES the reversed spec ↔ the existing code. Ground every element in the
-      CODE (read the source files listed below) but ANCHOR each to a spec id from
+      Reverse-engineer the BACKEND LANE's master plan (the target backend-plan.md in
+      context — it is the BROWNFIELD plan template) — the tech-agnostic HLD that
+      MEDIATES the reversed spec + domain model ↔ the existing code. Ground every element
+      in the CODE (read the source files listed below) but ANCHOR each to a spec id from
       the reversed spec (in context) so §4 Traceability is complete and the doc is
       forward-compatible. Guidance: {{feature_name}}
 
@@ -451,10 +608,12 @@ workflow:
       it toward any reference architecture; the technical standards in context are a
       vocabulary to NAME what you find, never a target to bend the code toward.
       Rules:
-      - THE SPEC IS THE ONLY DOMAIN INPUT. You have the reversed spec + the code's
-        actual STRUCTURE — and NO domain rule files. Realise the spec ids; introduce
-        no domain rule the spec omits. A concept the code exhibits but the spec lacks
-        → surface it (it belongs in the spec) and record a §5 DA-n; do not smuggle it in.
+      - THE SPEC AND THE MODEL ARE THE ONLY DOMAIN INPUTS. You have the reversed spec,
+        the reversed domain model and the code's actual STRUCTURE — and NO domain rule
+        files. Realise the spec ids; introduce no domain rule neither document states. A
+        concept the code exhibits but both lack → surface it (it belongs in the spec or
+        the model) and record a §5 DA-n; do not smuggle it in. DO NOT EDIT
+        domain-model.md — it is spec-tier and read-only here.
       - STRUCTURE FOLLOWS THE CODE. Fill §1.1 As-Built Architecture from the code's
         real shape (its folders / projects / modules — name the style, don't prescribe
         one). Then create ONE §2 subsection per structural axis the slice's code
@@ -464,11 +623,14 @@ workflow:
         fits no textbook layer (a UI tier, a worker, a shared library) gets its own
         section; a layer the code lacks does NOT appear.
       - KEEP THE NEUTRAL ANCHORS (the template pins these): §1.2 is the domain/data
-        MODEL and MUST match the spec's Key Entities / Business Rules (same names,
-        cite BR-/CN-) with cross-slice References-by-id kept here; one §2 subsection
-        is 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).
+        MODEL and MUST match the CONTEXT'S DOMAIN MODEL exactly — the same entity and
+        value-object NAMES, the same boundary, the same lifecycle states — with
+        cross-slice References-by-id kept here. Every BR-nnn the model defines gets a
+        named ENFORCEMENT POINT in this plan: cite it by id and NEVER restate what it
+        says, because the model is the only place that text lives. One §2 subsection is
+        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).
       - 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
@@ -486,27 +648,28 @@ 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: design.md realises the spec's FR/BR/CN-, design.ui.md realises the
-  # spec's UX- and the user stories' interaction, and it CONSUMES design.md's contracts
-  # rather than restating them. Both are in context for exactly that reason.
-  - id: ctx_reverse_ui_design
+  # 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.
+  - id: ctx_reverse_ui_plan
     condition: "{{ui_lane}} == true"
     action: build_context
     context:
-      - { path: "{{ui_design_doc}}" }             # the scaffolded code-derived lane template = structure + embedded guidance
+      - { 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: "{{design_doc}}" }                # the service design — the contracts the UI consumes, never re-specified here
+      - { path: "{{backend_plan}}" }              # the backend plan — the contracts the UI consumes, never re-specified here
+      - { 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
-  - id: reverse_ui_design
+  - id: reverse_ui_plan
     condition: "{{ui_lane}} == true"
     action: agent_author
     include_standards: true                        # the lane's sticky technical set (reference only — the CODE wins)
     tools: Read   # same, for the lane's surface ({{ui_source_files}})
-    output_target: { type: file, path: "{{ui_design_doc}}" }
+    output_target: { type: file, path: "{{frontend_plan}}" }
     task: |
-      Reverse-engineer the FRONTEND LANE's high-level design (the target design.ui.md
-      in context — it is this project's code-derived UI design template) for the
+      Reverse-engineer the FRONTEND LANE's master plan (the target frontend-plan.md
+      in context — it is this project's code-derived UI plan template) for the
       aggregate '{{feature_name}}', FROM ITS UI CODE. Fill the template; preserve its
       section order.
 
@@ -516,9 +679,11 @@ workflow:
       surface with no loading states is recorded as having none, NEVER as needing them.
       Rules:
       - STAY IN THE LANE. Realise the spec's Experience Standards (UX-) and the
-        interaction its User Stories imply. The service design (in context) supplies
+        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.
+        contradict them, and introduce no server-side behaviour here. 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.
       - 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
@@ -543,8 +708,8 @@ workflow:
     context:
       - { path: .appweaver/templates/source-map-template.md }   # the sidecar structure
       - { path: "{{spec_file}}" }
-      - { path: "{{design_doc}}" }
-      - { path: "{{ui_design_doc}}", optional: true }   # the lane's design, where this slice has one
+      - { path: "{{backend_plan}}" }
+      - { 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
     action: agent_author
@@ -554,14 +719,14 @@ workflow:
     task: |
       Author the source-map sidecar (the target in context) from the template,
       for aggregate '{{feature_name}}'. It is the SOURCE ANCHOR of the traceability
-      spine — it keeps spec.md / design.md clean while recording provenance here.
+      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 design element (§/name) that now describe it, with CONFIDENCE
+        and the backend-plan element (§/name) that now describe it, with CONFIDENCE
         (certain | inferred). EVERY source file MUST appear — the Fidelity gate
         checks full coverage both ways.
       - Where this slice has a UI half, its files map the same way, to the UX-/US-
-        they realise and the design.ui.md section (§/name) that describes them —
+        they realise and the frontend-plan.md section (§/name) that describes them —
         one spine, both lanes. UI files to map: {{ui_source_files}}
       - Also map DB tables, endpoints, and background jobs the slice owns.
       - Fill the Seam section: the boundary this slice owns (endpoint / table
@@ -573,35 +738,51 @@ workflow:
       - Baseline commit = the inventory HEAD.
       Source files to map: {{source_files}}
 
-  # ═══════════════ FIDELITY — does spec+design describe the CODE? ═════════════
-  # spec/design ↔ CODE (NOT spec ↔ design). The agent can READ the source files.
-  # BLOCKING gaps = unmapped code / fabricated spec-or-design (structural). The
-  # rest (inferred items, quirks, missing-invariant candidates) are REVIEW items
-  # → written to an Adopt Review report and closed OUT OF BAND (Brownfield B1·R).
+  # ═══════ FIDELITY — do spec + model + plans describe the CODE? ══════════════
+  # documents ↔ CODE (NOT document ↔ document). The agent can READ the source files.
+  # BLOCKING gaps = unmapped code / a fabricated spec id, model element or plan element
+  # (structural). The rest (inferred items, quirks, missing-invariant candidates) are
+  # REVIEW items → written to an Adopt Review report and closed OUT OF BAND (Brownfield
+  # B1·R).
+  #
+  # THE MODEL IS JUDGED THE SAME WAY AS EVERYTHING ELSE, and it is the document most
+  # likely to be embellished: a reverse that "tidies" an anemic legacy slice into a clean
+  # aggregate produces a model the code does not have, which every later plan and slice
+  # gate would then be checked against. An invented entity, boundary or invariant is a
+  # fabrication exactly as an invented FR- is.
   - id: fidelity
     action: agent_query
     context:
       - "{{spec_file}}"
-      - "{{design_doc}}"
-      - { path: "{{ui_design_doc}}", optional: true }   # the lane's design, where this slice has one
+      - "{{domain_model}}"
+      - "{{backend_plan}}"
+      - { path: "{{frontend_plan}}", optional: true }   # the lane's plan, where this slice has one
       - "{{feature_dir}}/source-map.md"
       - "{{concept_path}}"
     include_standards: false
-    tools: Read   # the check is spec/design vs CODE; with no code it degrades to spec vs design and certifies fabrication as ok
-    schema: { ok: true, report_needed: false, blocking_gaps: [ { severity: "high", artefact: "<source file / spec id / design element>", kind: "unmapped-code | fabricated-spec | fabricated-design", detail: "<why>" } ], review_items: [ { kind: "inferred | as-built-quirk | missing-invariant | confidence", where: "<spec/design/source-map location>", note: "<what to confirm out of band>" } ] }
+    tools: Read   # the check is documents vs CODE; with no code it degrades to doc vs doc and certifies fabrication as ok
+    schema: { ok: true, report_needed: false, blocking_gaps: [ { severity: "high", artefact: "<source file / spec id / model element / plan element>", kind: "unmapped-code | fabricated-spec | fabricated-model | fabricated-plan", detail: "<why>" } ], review_items: [ { kind: "inferred | as-built-quirk | missing-invariant | confidence", where: "<spec/model/plan/source-map location>", note: "<what to confirm out of band>" } ] }
     mock: { ok: true, report_needed: false, blocking_gaps: [], review_items: [] }
     task: |
       FIDELITY CHECK — do the reversed documents actually describe the CODE
-      (spec/design ↔ CODE, NOT spec ↔ design)? Use the source-map (in context) and
+      (documents ↔ CODE, NOT document ↔ document)? Use the source-map (in context) and
       READ the slice's source files (the concept's `source_files`, under
-      {{module_dir}}). Where design.ui.md is in context, it is judged the same way
+      {{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-design, and a
+      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:
       - BLOCKING (structural — set ok=false if any):
-        (1) unmapped-code: a source file with NO spec/design home in the source-map;
-        (2) fabricated-spec / fabricated-design: a spec id or design element with NO
-            basis in the code (reverse-engineering must not invent behaviour).
+        (1) unmapped-code: a source file with NO home in the source-map;
+        (2) fabricated-spec / fabricated-model / fabricated-plan: a spec id, model
+            element or plan element with NO basis in the code (reverse-engineering must
+            not invent behaviour or structure). For the MODEL specifically: an entity or
+            value object the code does not have, an aggregate boundary it does not draw,
+            a lifecycle state it never enters, or a BR-nnn whose rule nothing enforces.
+            An anemic slice reversing as an anemic model is CORRECT, not a gap.
+      - ONLY ONE AGGREGATE SECTION IS THIS RUN'S. domain-model.md is the CONTEXT's and
+        may already carry sections from earlier adopted slices — judge ONLY the aggregate
+        '{{feature_name}}' reversed here. Do not report a sibling aggregate as unmapped
+        because this slice's code does not contain it.
       - REVIEW (does NOT block ok — these are the Adopt review worklist, closed out
         of band): items marked "(inferred)"; as-built quirks the code shows but the
         spec under-states; invariants the code enforces that may be missing/weak;
@@ -620,7 +801,7 @@ workflow:
     condition: "{{report_needed}} == true"
     action: agent_author
     include_standards: false
-    context: ["{{spec_file}}", "{{design_doc}}", "{{feature_dir}}/source-map.md"]
+    context: ["{{spec_file}}", "{{domain_model}}", "{{backend_plan}}", "{{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 aggregate '{{feature_name}}' —
@@ -637,22 +818,23 @@ workflow:
         spec.md (a resolved [NEEDS CLARIFICATION] / Assumption) or log a deviation.
         Review items: {{review_items}}
       - "## How to proceed": resolve blocking gaps first; then the slice is a normal
-        feature — run /appweaver analyze-plan (spec↔design gate) if desired, then
-        drive every change through the CR delta loop. If a change edits untested legacy
-        behaviour with blast radius, characterize just that surface first (optional
-        on-touch fence) — it is not a required phase.
+        feature — run /appweaver analyze-plan (the spec↔plan gate, which also checks both
+        plans against the context's domain model) if desired, then drive every change
+        through the CR delta loop. If a change edits untested legacy behaviour with blast
+        radius, characterize just that surface first (optional on-touch fence) — it is
+        not a required phase.
       Return the report markdown only.
 
   - id: fidelity_gate
     action: verify_context
     require_true: fidelity_ok
     on_false: stop
-    on_false_message: "Fidelity FAILED for {{feature_name}} — the reversed spec/design do not match the code (blocking gaps: {{blocking_gaps}}). See specs/{{feature_name}}/adopt-review-report.md. Fix the unmapped code / remove fabricated items (re-read the source, refine spec.md + design.md + source-map.md), then re-run /appweaver adopt (after removing the dir) or resolve out of band."
+    on_false_message: "Fidelity FAILED for {{feature_name}} — the reversed documents do not match the code (blocking gaps: {{blocking_gaps}}). See specs/{{feature_name}}/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."
 
   # ═══════════ OKF CONCEPT — COMPLETE the shallow scan concept (deep reverse) ═══
   # onboard wrote this aggregate's OKF concept SHALLOW (a discovery stub — enough to pick the
-  # feature). Now that the deep reverse produced a TRUSTWORTHY spec.md + design.md +
-  # source-map.md, COMPLETE the concept: deepen its detail to the reversed reality, LINK the
+  # feature). Now that the deep reverse produced a TRUSTWORTHY spec.md + domain-model.md +
+  # backend-plan.md + source-map.md, COMPLETE the concept: deepen its detail to the reversed reality, LINK the
   # authored artifacts, refresh source_files, and mark it ADOPTED. RECONCILE, not rewrite —
   # keep OKF format + the bundle links; do NOT touch the Depends-On / Cross-References
   # sections (xref_record owns those, next). Runs only after fidelity passes (deepened from
@@ -663,7 +845,8 @@ workflow:
     context:
       - { path: "{{concept_path}}" }                          # the shallow onboard concept to complete
       - { path: "{{spec_file}}" }                             # the deep reversed spec (entities, US, BR/CN/DC/IC)
-      - { path: "{{design_doc}}" }                            # the deep reversed design (components, ports, integrations)
+      - { path: "{{domain_model}}" }                           # the deep reversed model (entities, boundary, invariants)
+      - { path: "{{backend_plan}}" }                            # the deep reversed plan (components, ports, integrations)
       - { 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
@@ -673,14 +856,18 @@ workflow:
     task: |
       COMPLETE the OKF aggregate concept for '{{feature_name}}' at {{concept_path}} — onboard
       wrote it SHALLOW (a discovery stub from the whole-repo scan). The deep reverse has now
-      produced a TRUSTWORTHY spec.md + design.md + source-map.md (in context); deepen the
+      produced a TRUSTWORTHY spec.md + domain-model.md + backend-plan.md + source-map.md (in
+      context); deepen the
       concept to match and LINK those artifacts. Follow the OKF concept template in context.
       RECONCILE, do NOT rewrite:
       - DEEPEN the responsibilities + the owned entities / value objects / domain events /
-        commands (user stories) / API endpoints / persistence to match the reversed spec +
-        design — correct any drift the shallow scan got wrong (the deep docs win).
-      - LINK the deep artifacts: add bundle links to specs/{{feature_name}}/spec.md, design.md,
-        and source-map.md so the concept points at the deep truth.
+        commands (user stories) / API endpoints / persistence to match the reversed spec,
+        model and plan — the ENTITIES and VALUE OBJECTS come from domain-model.md, which is
+        the authority on them; correct any drift the shallow scan got wrong (the deep docs
+        win).
+      - LINK the deep artifacts: add bundle links to specs/{{feature_name}}/spec.md,
+        backend-plan.md, source-map.md and the context's domain-model.md so the concept
+        points at the deep truth.
       - Refresh `source_files` from the source-map (grouped by the code's OWN folders, per
         OKF), and set `timestamp` to the baseline (inventory HEAD) commit time.
       - Update frontmatter: keep `origin: reverse-engineered`; mark the concept ADOPTED /
@@ -694,7 +881,7 @@ workflow:
     outputs:
       - { name: concept_completed, from: "$.files" }
 
-  # 3b. OKF cross-references (brownfield seed). The reversed design.md now names this
+  # 3b. OKF cross-references (brownfield seed). The reversed backend-plan.md now names this
   #     slice's cross-aggregate references (§1 References-by-id) + integration contracts
   #     (its External integrations table, IC-); record them into the shared OKF bundle — a
   #     Cross-References row in every
@@ -706,7 +893,7 @@ workflow:
     action: execute_script
     script: { ref: xref }
     subcommand: record
-    args: ["--using", "{{feature_name}}", "--design", "{{design_doc}}", "--bundle", "{{bundle_dir}}", "--origin", "reverse-engineered"]
+    args: ["--using", "{{feature_name}}", "--design", "{{backend_plan}}", "--bundle", "{{bundle_dir}}", "--origin", "reverse-engineered"]
     outputs:
       - { name: xref_wrote,      from: "$.wrote" }
       - { name: xref_edge_count, from: "$.edge_count" }
@@ -738,7 +925,7 @@ workflow:
     action: build_context
     context:
       - { path: "{{spec_file}}" }                                          # the feature's real BR-/CN-/DC-/IC-
-      - { path: "{{design_doc}}" }
+      - { path: "{{backend_plan}}" }
       - { path: "{{feature_dir}}/source-map.md" }
       - { path: "guardrails/projects/{{gov_domain}}/domain-rule-bindings.md", optional: true }
       - { path: .appweaver/RULE-PARTITION.md }                                       # the rule-partition authority (which command reads what)
@@ -751,7 +938,7 @@ workflow:
       RECONCILE the domain rule-file set in guardrails/projects/{{gov_domain}}/domain/ with the
       newly-adopted feature '{{feature_name}}'. onboard authored these rule files from the
       whole-repo scan with per-feature specifics marked `PROVISIONAL — reconciled at
-      adopt`. READ this feature's reversed spec.md + design.md + source-map.md (in
+      adopt`. READ this feature's reversed spec.md + backend-plan.md + source-map.md (in
       context — the real evidence) and the EXISTING rule files under
       guardrails/projects/{{gov_domain}}/.
 
@@ -780,7 +967,7 @@ workflow:
     action: build_context
     context:
       - { path: "{{constitution_technical_file}}" }
-      - { path: "{{design_doc}}" }
+      - { path: "{{backend_plan}}" }
       - { path: "{{feature_dir}}/source-map.md" }
   - id: reconcile_technical
     condition: "{{reconcile_governance}} == true"   # HELD — governance reconcile paused (see vars)
@@ -790,7 +977,7 @@ workflow:
     task: |
       RECONCILE the TECHNICAL constitution (target in context) with the adopted feature
       '{{feature_name}}'. onboard discovered the technology principle SET from the scan and
-      marked per-feature code coordinates `PROVISIONAL`. READ this feature's design.md +
+      marked per-feature code coordinates `PROVISIONAL`. READ this feature's backend-plan.md +
       source-map.md (in context — the code-coordinate bridge: real file paths / type names).
 
       RECONCILE, do NOT re-author:
@@ -921,8 +1108,10 @@ workflow:
 outputs:
   feature_dir: "{{feature_dir}}"
   spec_file: "{{spec_file}}"
-  design_doc: "{{design_doc}}"
-  ui_design_doc: "{{ui_design_doc}}"   # empty where this slice has no UI half
+  backend_plan: "{{backend_plan}}"
+  frontend_plan: "{{frontend_plan}}"   # empty where this slice has no UI half
+  domain_model: "{{domain_model}}"     # the CONTEXT's, shared — this run ADDED an aggregate section to it
+  bounded_context: "{{context}}"
   ui_lane: "{{ui_lane}}"
   ui_count: "{{ui_count}}"
   source_map: "{{feature_dir}}/source-map.md"
@@ -936,4 +1125,4 @@ outputs:
   composed_file: "{{composed_file}}"
   technical_reconcile_ok: "{{technical_ok}}"
   domain_reconcile_ok: "{{domain_ok}}"
-  next: "Adopted {{feature_name}} (spec.md + design.md + source-map.md, v1.0) and COMPLETED its OKF concept (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 design.ui.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. 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/projects/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in specs/{{feature_name}}/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 + backend-plan.md + source-map.md, v1.0) and ADDED its aggregate section to 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. Other features in this context keep their own aggregate sections untouched. COMPLETED its OKF concept (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. 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/projects/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in specs/{{feature_name}}/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."