aw-spec-cli 0.1.18 → 0.1.19

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

@@ -42,6 +42,22 @@
 # spec.md — analyze-plan already conformed the plans to it, so the plan is the complete,
 # authoritative source for WHICH elements exist, where each lives and what surface they
 # publish, and anything missing from it is fixed in `plan`, never compensated for here.
+#
+# AND THAT SENTENCE IS NOW CHECKED. "analyze-plan already conformed them" was an assumption
+# about the order the operator ran things in: the lane gates test that the plan FILE EXISTS
+# and nothing more, so `plan` → edit spec.md → `implement` generated at full length from a
+# plan nobody had held against the spec it now contradicts. analyze-plan leaves a receipt of
+# the bytes it proved and plan-gate-check reads it here, on the bootstrap path, before any
+# lane generates. A feature with no receipt has simply never been gated since the receipt
+# existed — reported, never refused. One that HAS a receipt and no longer matches it stops.
+# 3.2.0 — AND NOT delta-spec.md EITHER. The change path used to inline it "only so the
+# paired tests can cite traceability ids", which made the rule true on the bootstrap path
+# and false on the one where changes actually ship: a document in the payload is a document
+# the generator can reason from, so a gap in a delta plan could be quietly filled from the
+# requirement text and the plan never found to be wrong. Both paths now carry plan + model
+# and nothing else. The ids are still cited and still required — the delta plan names the
+# spec id each element serves, which is exactly what analyze-plan-delta conformed, and an
+# element naming none is a planning gap to surface rather than a traceability to invent.
 # But since the model split a plan CITES an invariant by id and never restates it, so the
 # bounded context's domain-model.md is in context too, as the authority on the entity
 # names, the aggregate boundary, the lifecycle states and the TEXT of every BR-nnn the plan
@@ -76,6 +92,14 @@
 # found only elsewhere in the repository is the service lane's, and accepting it is how a
 # frontend that was never scaffolded is generated into anyway and reports green.
 #
+# A LANE'S GAP DISABLES THAT LANE, NOT THE RUN. Three things a lane needs are checked per
+# lane and reported per lane: its source path is on disk, its plan is there, and a project
+# is scaffolded under it. Any of them missing skips that lane with the command that fixes
+# it named, and every other declared lane still generates; only when NOTHING can run does
+# the run stop, with all the reasons printed. The whole-run stop is reserved for states
+# with no correct lane to fall back on — no lane declared at all, a lane declaring no
+# source path, and two lanes claiming overlapping subtrees.
+#
 # WHAT IT DOES NOT DO. It never writes spec.md, a master plan or the domain model, and it
 # never closes a change — finalize-delta merges the change's spec and model halves,
 # analyze-slice verifies the slice, and close-delta archives it and bumps the version.
@@ -91,8 +115,8 @@
 # =============================================================================
 
 name: aw-spec-implement
-description: "Generate the aggregate's source files and paired tests from its lane plans — the backend lane from backend-plan.md when a backend stack is declared, the frontend lane from frontend-plan.md when a frontend stack is, both when both are. One command covers backend-only, frontend-only and full-stack projects and absorbs the former implement-ui and implement-delta. Self-detecting off the changes on disk — with none open it generates from the master plans; with one or more open it ASKS which change and generates only what that change's delta plans mark ADDED or MODIFIED, leaving the masters untouched. Every lane is gated on its own plan and its own scaffolded project, and a lane missing either is reported and skipped rather than failing the other lane; each runnable lane confirms before it writes. Model-driven, and it does not read the spec — analyze-plan already conformed the plans to it. The plan says WHAT to build; the bounded context's domain-model.md, in context alongside it, says what the domain IS — the entity names, the boundary and the text of every invariant the plan cites by id — joined on the delta path by that change's own model delta, since the master is not merged until finalize-delta. The stack binds here from the lane declaration and the constitution halves; the plans stay technology-agnostic."
-version: 3.0.0
+description: "Generate the aggregate's source files and paired tests from its lane plans — the backend lane from backend-plan.md when a backend stack is declared, the frontend lane from frontend-plan.md when a frontend stack is, both when both are. One command covers backend-only, frontend-only and full-stack projects and absorbs the former implement-ui and implement-delta. Self-detecting off the changes on disk — with none open it generates from the master plans; with one or more open it ASKS which change and generates only what that change's delta plans mark ADDED or MODIFIED, leaving the masters untouched. Every lane is gated on its own source path, its own plan and its own scaffolded project, and a lane missing any of them is reported and skipped rather than failing the other lane; each runnable lane confirms before it writes. Model-driven, and it does not read the spec — analyze-plan already conformed the plans to it. The plan says WHAT to build; the bounded context's domain-model.md, in context alongside it, says what the domain IS — the entity names, the boundary and the text of every invariant the plan cites by id — joined on the delta path by that change's own model delta, since the master is not merged until finalize-delta. The stack binds here from the lane declaration and the constitution halves; the plans stay technology-agnostic."
+version: 3.4.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -138,6 +162,20 @@ vars:
   delta_frontend_plan: ""
   delta_frontend_plan_exists: "false"
   wave: ""
+  # THE GATE RECEIPT — was this feature's plan pair ever PROVEN against this spec, and has
+  # anything moved since. analyze-plan writes it on a green master run; this phase is the
+  # reader. Bootstrap path only: a delta generates from delta plans, which analyze-plan-delta
+  # gates, and the master receipt says nothing about those.
+  gate_tracked: "false"
+  gate_fresh: "false"
+  gate_reason: ""
+  gate_at: ""
+  # DEFAULTED PERMISSIVE, DELIBERATELY, and it is the one flag here that is. Every tree that
+  # predates the receipt has none, and "never gated" is an unknown, not a stale plan —
+  # refusing on a missing file would block every existing feature on its first run. The flag
+  # is lowered only by a receipt that EXISTS and no longer matches: that tree has been through
+  # the gate once, so the bytes moving since is a fact, not an absence of one.
+  may_generate: "true"
   # PER-LANE STATE. Each lane resolves its own plan, its own project and its own answer;
   # a lane that is not declared never resolves any of them and its steps never run.
   # The engine has no compound conditions, so each AND is an ordered assignment: a step
@@ -182,22 +220,32 @@ workflow:
 
   # 0. THE LANE MODEL. lane-verify with NO --require, because this phase requires neither
   #    kind: a backend-only and a frontend-only project are both correct states, and which
-  #    lanes exist is exactly what it is here to find out. It still reports every DECLARED
-  #    lane whose source path is empty, missing or overlapping another's — a stack named
-  #    against a path that is not there is a mistake in a phase that writes code — and it
-  #    always exits 0, so the reason reaches the gate below as text.
+  #    lanes exist is exactly what it is here to find out.
+  #
+  #    --allow-missing-root, because a lane whose source path is not on disk is THAT LANE'S
+  #    gap, not the run's. This phase is per-lane throughout — a missing plan or a missing
+  #    project is reported at step 5 and the other lane still generates — and a missing root
+  #    is the same kind of gap, most often a declared frontend that `foundation` has not
+  #    unpacked yet. With the check left on it arrives here instead, as a whole-run stop
+  #    that takes the ready lane down with it. It is re-checked per lane at step 5 from
+  #    `*_root_exists`, which lane-verify reports whether or not the on-disk half is armed.
+  #
+  #    What still stops the run: no lane declared at all, a lane declaring no source path,
+  #    and two lanes claiming overlapping subtrees. Those are declaration errors with no
+  #    correct lane to fall back to, and none of them is a state any phase can work around.
   - id: lane_verify
     action: execute_script
     on_error: continue
     script: { ref: actions }
     subcommand: lane-verify
-    args: ["--command", "/appweaver implement"]
+    args: ["--command", "/appweaver implement", "--allow-missing-root"]
     outputs:
       - { name: lane_ok,        from: "$.ok" }
       - { name: lane_issues,    from: "$.message" }
       - { name: be_declared,    from: "$.backend_declared" }
       - { name: be_lane_id,     from: "$.backend_lane_id" }
       - { name: be_source_path, from: "$.backend_source_path" }
+      - { name: be_root_exists, from: "$.backend_root_exists" }
       - { name: be_profile,     from: "$.backend_profile" }
       - { name: be_title,       from: "$.backend_title" }
       - { name: be_language,    from: "$.backend_language" }
@@ -207,6 +255,7 @@ workflow:
       - { name: fe_declared,    from: "$.frontend_declared" }
       - { name: fe_lane_id,     from: "$.frontend_lane_id" }
       - { name: fe_source_path, from: "$.frontend_source_path" }
+      - { name: fe_root_exists, from: "$.frontend_root_exists" }
       - { name: fe_profile,     from: "$.frontend_profile" }
       - { name: fe_title,       from: "$.frontend_title" }
       - { name: fe_language,    from: "$.frontend_language" }
@@ -318,6 +367,10 @@ workflow:
     outputs:
       - { name: cr_id,                     from: "$.cr_id" }
       - { name: cr_dir,                    from: "$.cr_dir" }
+      # Resolved for reporting and DELIBERATELY NOT put in any context — see the header.
+      # This phase realises the delta PLAN; the requirement text reaching the generator is
+      # what lets a gap in the plan be compensated for instead of found. Do not add it to
+      # ctx_backend_delta / ctx_frontend_delta.
       - { name: delta_spec,                from: "$.delta_spec" }
       # THIS CHANGE'S MODEL HALF — the structure the delta plans realise. It is context for
       # every generating lane, exactly as the master model is: the delta plan cites the
@@ -350,6 +403,49 @@ workflow:
     action: set
     vars: { fe_plan: "{{delta_frontend_plan}}", fe_plan_ok: "{{delta_frontend_plan_exists}}" }
 
+  # 3b. WERE THESE PLANS PROVEN AGAINST THIS SPEC. This phase does not read spec.md — the
+  #     header's reason is "analyze-plan already conformed the plans to it", which was an
+  #     assumption about the order the operator ran things in and was checked by nothing:
+  #     the lane gates below test that the plan FILE EXISTS and stop there. `plan`, edit
+  #     spec.md, `implement` therefore generated from a plan that was never held against the
+  #     spec it now contradicts, silently and at full length.
+  #
+  #     plan-gate-check compares today's bytes against the receipt analyze-plan left when it
+  #     passed — spec.md, the context's domain-model.md and each gated lane plan. The plans'
+  #     own `**Version**:` headers cannot answer this and must not be used: close-delta stamps
+  #     them and spec.md to the same number in lockstep whether or not a plan was re-derived,
+  #     so the comparison reads equal always.
+  #
+  #     BOOTSTRAP ONLY. A delta run generates from delta plans that analyze-plan-delta gates;
+  #     the master receipt is silent about them, and reading it there would refuse a change
+  #     for drift in documents this run is not building from.
+  - id: plan_gate_check
+    condition: "{{mode}} == bootstrap"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-gate-check
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: gate_tracked, from: "$.tracked" }
+      - { name: gate_fresh,   from: "$.gate_fresh" }
+      - { name: gate_reason,  from: "$.reason" }
+      - { name: gate_at,      from: "$.gated" }
+
+  #     The ordered assignment is the AND: only a TRACKED feature can lower the flag, and
+  #     what lowers it is the gate no longer being fresh. An untracked one never reaches
+  #     this step's assignment and generates, which is the whole accommodation for trees
+  #     that have not been gated since the receipt existed.
+  - id: flag_gate_block
+    condition: "{{gate_tracked}} == true"
+    action: set
+    vars: { may_generate: "{{gate_fresh}}" }
+
+  - id: require_gate_fresh
+    action: verify_context
+    require_true: may_generate
+    on_false: stop
+    on_false_message: "implement REFUSED — the master plans are no longer the ones analyze-plan passed: {{gate_reason}}. This phase generates from the plans and does NOT read the spec, on the strength of that gate having conformed them to it, so generating now would realise a plan against requirements nobody checked it against. Re-run /appweaver analyze-plan — it re-checks all four checks, repairs the drifting plan on approval, and re-issues the receipt — then re-run /appweaver implement. If what changed was a plan you re-derived with /appweaver plan main, that is the same path: the re-derived plans have not been gated yet. Nothing was generated."
+
   # 4. THE PROJECT each declared lane generates INTO. Deterministic structure gate:
   #    detect-project searches the LANE'S OWN subtree for an ecosystem manifest (.sln/
   #    .csproj, pom.xml, build.gradle, package.json, go.mod, Cargo.toml, pyproject.toml),
@@ -396,6 +492,12 @@ workflow:
     require_true: be_plan_ok
     on_false: continue
     on_false_message: "BACKEND LANE SKIPPED — lane `{{be_lane_id}}` ({{be_title}}) is declared in .appweaver/stacks.json, but the plan this run generates from is not there: {{be_plan}}. Run /appweaver plan (then /appweaver analyze-plan for the masters, or /appweaver analyze-plan-delta for a change) and re-run implement. Nothing is generated for this lane; any other declared lane still runs."
+  - id: warn_be_root
+    condition: "{{be_declared}} == true"
+    action: verify_context
+    require_true: be_root_exists
+    on_false: continue
+    on_false_message: "BACKEND LANE SKIPPED — lane `{{be_lane_id}}` ({{be_title}}) declares source path `{{be_source_path}}` in .appweaver/stacks.json, and that path is not a directory in this repository. A lane owns its subtree and this phase writes into it, so there is nothing to generate into: unpack a project there with /appweaver foundation <FoundationName> <AppName> where a bundle ships for {{be_profile}}, create one with the stack's own tooling, or re-run /appweaver select-stack and point the lane at the directory that really holds its source. Nothing is generated for this lane; any other declared lane still runs."
   - id: warn_be_project
     condition: "{{be_declared}} == true"
     action: verify_context
@@ -408,6 +510,12 @@ workflow:
     require_true: fe_plan_ok
     on_false: continue
     on_false_message: "FRONTEND LANE SKIPPED — lane `{{fe_lane_id}}` ({{fe_title}}) is declared in .appweaver/stacks.json, but the plan this run generates from is not there: {{fe_plan}}. Run /appweaver plan (then /appweaver analyze-plan for the masters, or /appweaver analyze-plan-delta for a change) and re-run implement. Nothing is generated for this lane; any other declared lane still runs."
+  - id: warn_fe_root
+    condition: "{{fe_declared}} == true"
+    action: verify_context
+    require_true: fe_root_exists
+    on_false: continue
+    on_false_message: "FRONTEND LANE SKIPPED — lane `{{fe_lane_id}}` ({{fe_title}}) declares source path `{{fe_source_path}}` in .appweaver/stacks.json, and that path is not a directory in this repository. A lane owns its subtree and this phase writes into it, so there is nothing to generate into: unpack a project there with /appweaver foundation <FoundationName> <AppName> where a bundle ships for {{fe_profile}}, create one with the stack's own tooling, or re-run /appweaver select-stack and point the lane at the directory that really holds its source. Nothing is generated for this lane; any other declared lane still runs."
   - id: warn_fe_project
     condition: "{{fe_declared}} == true"
     action: verify_context
@@ -415,14 +523,18 @@ workflow:
     on_false: continue
     on_false_message: "FRONTEND LANE SKIPPED — no frontend project found under the {{fe_lane_id}} lane's source path `{{fe_source_path}}`. detect-project searched that subtree and then the whole repository, and answered at scope `{{fe_project_scope}}`; `lane` is the only scope this lane accepts. Scaffold a project there — /appweaver foundation <FoundationName> <AppName> where a bundle ships for {{fe_profile}}, or the stack's own tooling — and re-run implement. A manifest found elsewhere in the repository does NOT count: that one belongs to another lane, and generating this lane's code against it is how a frontend that was never built reports green."
 
-  # 6. RUNNABLE = declared AND its plan is there AND its project is there, as an ordered
-  #    assignment plus a knockdown, since the engine has no compound conditions. An
-  #    undeclared lane stays false either way — its `declared` value is what the raise
-  #    assigns.
+  # 6. RUNNABLE = declared AND its source path is on disk AND its plan is there AND its
+  #    project is there, as one ordered assignment plus a knockdown per condition, since
+  #    the engine has no compound conditions. An undeclared lane stays false either way —
+  #    its `declared` value is what the raise assigns.
   - id: be_runnable_raise
     condition: "{{be_plan_ok}} == true"
     action: set
     vars: { be_runnable: "{{be_declared}}" }
+  - id: be_runnable_clear_root
+    condition: "{{be_root_exists}} == false"
+    action: set
+    vars: { be_runnable: "false" }
   - id: be_runnable_clear
     condition: "{{be_project_ok}} == false"
     action: set
@@ -431,6 +543,10 @@ workflow:
     condition: "{{fe_plan_ok}} == true"
     action: set
     vars: { fe_runnable: "{{fe_declared}}" }
+  - id: fe_runnable_clear_root
+    condition: "{{fe_root_exists}} == false"
+    action: set
+    vars: { fe_runnable: "false" }
   - id: fe_runnable_clear
     condition: "{{fe_project_ok}} == false"
     action: set
@@ -471,7 +587,7 @@ workflow:
     action: verify_context
     require_true: generate_any
     on_false: stop
-    on_false_message: "Nothing to implement — no declared lane is both ready and confirmed. Either every declared lane was skipped for a reason printed above (its plan or its project is missing), or each one that was ready was declined at the prompt. Backend lane declared {{be_declared}}, ready {{be_runnable}}; frontend lane declared {{fe_declared}}, ready {{fe_runnable}}. Fix the reasons named above, or re-run and confirm a lane."
+    on_false_message: "Nothing to implement — no declared lane is both ready and confirmed. Either every declared lane was skipped for a reason printed above (its source path, its plan or its project is missing), or each one that was ready was declined at the prompt. Backend lane declared {{be_declared}}, ready {{be_runnable}}; frontend lane declared {{fe_declared}}, ready {{fe_runnable}}. Fix the reasons named above, or re-run and confirm a lane."
 
   # 8. EACH GENERATING LANE'S authoring MODE — the run's mode where the lane is going, and
   #    `skip` where it is not, which silences both of that lane's branches without a
@@ -490,18 +606,21 @@ workflow:
   #    backend's heading is keyed by mode (see the header). No blocking gate: an
   #    unconfigured project soft-continues, since the constitution halves still carry each
   #    lane's ratified base.
+  #
+  #    EACH LANE'S RULES ARE LOADED BESIDE ITS OWN STEPS, AND THE SECOND LANE REPLACES
+  #    THE FIRST'S. Both includes used to run here, before either lane generated — and
+  #    sticky standards only accumulate, so on a full-stack run the backend generator was
+  #    shown `## /aw-spec-implement-ui` and the frontend generator the service set. Each
+  #    prompt says which lane it is in, but it said so inside an envelope that contradicted
+  #    it, and the envelope is the part the model cannot argue with. The frontend include
+  #    now sits immediately before the FRONTEND sections below and passes replace, which
+  #    resets to the workflow's declared seed (ai-rules) before loading the UI set.
   - id: tech_select
     condition: "{{be_go}} == true"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
     with: { command: "{{be_tech_command}}" }
 
-  - id: tech_select_ui
-    condition: "{{fe_go}} == true"
-    action: include
-    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-implement-ui }
-
   # 10. Pre-execution hooks — see the hook-phase vars above.
   - id: resolve_pre_hooks
     action: execute_script
@@ -605,14 +724,22 @@ workflow:
   # ═══════════ BACKEND LANE — delta, generate ONLY what the change adds ════════
   # The delta plan is the authoritative source of WHAT changed — analyze-plan-delta already
   # conformed it to the delta spec. The MASTER plan is the BASE (the unchanged elements the
-  # delta depends on), and the delta spec is here ONLY so the paired tests can cite
-  # traceability ids.
+  # delta depends on).
+  #
+  # NO DELTA-SPEC HERE, exactly as the bootstrap path carries no spec. It used to be
+  # inlined "only so the paired tests can cite traceability ids", but a document in the
+  # payload is a document the generator can reason from, and the whole point of the
+  # contract is that this phase realises the PLAN: with the requirement text in reach, a
+  # gap in the plan can be silently compensated for from the spec and the plan is never
+  # found to be wrong. The ids are still available and still required — the delta plan
+  # cites the spec id each element serves, which is what analyze-plan-delta conformed.
+  # A plan that does not name an id is a planning gap to surface, and that is now visible
+  # instead of being papered over here.
   - id: ctx_backend_delta
     condition: "{{be_mode}} == delta"
     action: build_context
     context:
       - { path: "{{be_plan}}" }                      # this change's delta-backend-plan.md
-      - { path: "{{delta_spec}}", optional: true }
       - { path: "{{delta_model}}", optional: true }  # this change's MODEL half — what it ADDS to / CHANGES in the model
       - { path: "{{backend_plan}}", optional: true } # the master plan — READ ONLY, never amended here
       - { path: "{{domain_model}}", optional: true } # the master model — the domain as it stands BEFORE this change
@@ -642,9 +769,12 @@ workflow:
         winning wherever they differ — it is the newer statement, and the master has not
         been merged yet (finalize-delta does that after this phase). Read there what every
         BR-nnn the delta plan cites actually requires; the plan records WHERE each is
-        enforced and never restates it. You have NO domain rule files and NO spec beyond
-        the delta-spec's ids — if a domain specific is in none of them, STOP and surface it
-        (it is fixed in specify / plan / analyze-plan-delta), never invent it from memory.
+        enforced and never restates it. You have NO domain rule files and NO spec AT ALL —
+        not the master and not this change's delta-spec. The requirement ids are in the
+        delta plan, which cites the one each element serves; that is the whole of what you
+        get. If a domain specific is in neither the plan nor the model, STOP and surface it
+        (it is fixed in specify / plan / analyze-plan-delta), never invent it from memory
+        and never infer it from an id.
       - THE MODEL IS READ, NEVER MINED FOR WORK. Realise only what the DELTA PLAN calls
         for: an item in the model delta that no delta-plan element realises is a PLANNING
         gap — surface it, do not implement it. Everything in the master model that this
@@ -682,7 +812,10 @@ workflow:
         the port isn't present, code to it and note that as the prerequisite.
       - Author a paired test for every ADDED/MODIFIED behaviour / use-case / endpoint;
         derive the cases from the delta plan's pre/post/invariant contracts and cite the
-        delta-spec id (FR / BR / CN / DC / IC / US).
+        requirement id THE DELTA PLAN NAMES for that element (FR / BR / CN / DC / IC / US).
+        The spec is not in context: take the id from the plan and cite it verbatim, never
+        guess one from the element's shape. A delta-plan element that names no id is a
+        planning gap — surface it rather than inventing the traceability.
       - REGRESSION: for each element in the delta plan's "Regression targets", verify (add
         or adjust a test where needed) that the existing behaviour still holds after a
         shared element changed — but do NOT rewrite that existing behaviour.
@@ -714,6 +847,22 @@ workflow:
     outputs:
       - { name: okf_concept, from: "$.concept" }
 
+  # ══════════════ THE LANE SWAP — the frontend's rules replace the backend's ═══
+  # build_context already scoped the two lanes' PAYLOADS apart; this is the same boundary
+  # for their STANDARDS, which the envelope carries and which nothing used to reset. It
+  # runs here rather than up with the backend's include because standards accumulate:
+  # loading both before either lane generated is precisely what showed each generator the
+  # other lane's rule set. `replace` resets to the declared seed (ai-rules stays) and then
+  # loads `## /aw-spec-implement-ui`, so from here down the envelope is the frontend's.
+  #
+  # Nothing after the frontend sections regenerates backend code — the OKF steps that
+  # follow run include_standards: false — so the swap needs no undo.
+  - id: tech_select_ui
+    condition: "{{fe_go}} == true"
+    action: include
+    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-implement-ui, replace: "true" }
+
   # ═══════════ FRONTEND LANE — bootstrap, generate from the MASTER plan ════════
   # The experience twin of the service generation, one lane over. Its own build_context,
   # because the envelope persists across steps and the two lanes must not see each other's
@@ -815,7 +964,8 @@ workflow:
     action: build_context
     context:
       - { path: "{{fe_plan}}" }                       # this change's delta-frontend-plan.md
-      - { path: "{{delta_spec}}", optional: true }
+      # No delta-spec — see the service lane's note above: this phase realises the PLAN,
+      # and the ids the tests cite come from the plan's own rows.
       - { path: "{{delta_model}}", optional: true }   # this change's MODEL half — new terms, states and rules the UI must speak
       - { path: "{{frontend_plan}}", optional: true } # the master plan — READ ONLY, never amended here
       - { path: "{{domain_model}}", optional: true }  # the master model — the ubiquitous language as it stands BEFORE this change
@@ -846,9 +996,10 @@ workflow:
         READ TOGETHER, the delta winning wherever they differ — the master has not been
         merged yet. A TERM THIS CHANGE INTRODUCES OR RENAMES IS IN THE DELTA, and the UI
         must speak it exactly as the delta spells it, in labels, states and messages. Read
-        there what any BR-nnn the delta plan cites requires. NO domain rule files, and no
-        spec beyond the delta-spec's ids; if a domain specific is in none of them, STOP and
-        surface it.
+        there what any BR-nnn the delta plan cites requires. NO domain rule files, and NO
+        spec at all — not the master and not this change's delta-spec; the requirement ids
+        come from the delta plan, which cites the one each element serves. If a domain
+        specific is in neither the plan nor the model, STOP and surface it.
       - THE MODEL IS READ, NEVER MINED FOR WORK, and reading a rule is not permission to
         move it. Realise only what the DELTA PLAN calls for — an item in the model delta
         that no delta-plan element realises is a PLANNING gap, and a client-side check
@@ -872,7 +1023,9 @@ workflow:
         evaluation.
       - Author a paired test for every ADDED/MODIFIED screen, interaction and state,
         including the unwanted-behaviour states and an accessibility assertion per
-        interactive surface, citing the delta-spec id (UX-/US-/FR-/CN-/DC-/IC-/SC-).
+        interactive surface, citing the requirement id THE DELTA PLAN NAMES for that row
+        (UX-/US-/FR-/CN-/DC-/IC-/SC-). The spec is not in context: take the id from the
+        plan and cite it verbatim. A row that names no id is a planning gap — surface it.
       - REGRESSION: for each element in the delta plan's regression targets, verify (add or
         adjust a test where needed) that the existing behaviour still holds after a shared
         component or state container changed — but do NOT rewrite that behaviour.
@@ -1010,5 +1163,11 @@ outputs:
   delta_model: "{{delta_model}}"       # its second half on the delta path — empty on the bootstrap path
   okf_concept: "{{okf_concept}}"
   xref_edge_count: "{{xref_edge_count}}"
-  note: "Lanes come from .appweaver/stacks.json — backend declared {{be_declared}} (ready {{be_runnable}}, implemented {{be_go}}), frontend declared {{fe_declared}} (ready {{fe_runnable}}, implemented {{fe_go}}). A declared lane that was skipped printed its reason above and did not stop the other one; an undeclared lane produces nothing and that is not a failure. Each generating lane read its PLAN for what to build and {{domain_model}} for what the domain is — plus {{delta_model}} on the delta path, since the master model does not carry the change until finalize-delta merges it. Every one of those documents was READ and none was written: this phase generates code and nothing else."
+  # Bootstrap path only. tracked=false means this feature has never passed analyze-plan
+  # since the gate began leaving a receipt — an unknown, not a stale plan, and it blocks
+  # nothing.
+  plan_gate_tracked: "{{gate_tracked}}"
+  plan_gate_fresh: "{{gate_fresh}}"
+  plan_gate_at: "{{gate_at}}"
+  note: "Lanes come from .appweaver/stacks.json — backend declared {{be_declared}} (ready {{be_runnable}}, implemented {{be_go}}), frontend declared {{fe_declared}} (ready {{fe_runnable}}, implemented {{fe_go}}). A declared lane that was skipped printed its reason above and did not stop the other one; an undeclared lane produces nothing and that is not a failure. Each generating lane read its PLAN for what to build and {{domain_model}} for what the domain is — plus {{delta_model}} on the delta path, since the master model does not carry the change until finalize-delta merges it. Every one of those documents was READ and none was written: this phase generates code and nothing else. On the bootstrap path the plans were checked against analyze-plan's receipt before anything generated (tracked={{gate_tracked}}, fresh={{gate_fresh}}, gated {{gate_at}}) — tracked=false means this feature has never passed analyze-plan since the gate began recording what it proved, which is an unknown rather than a stale plan and blocks nothing; run /appweaver analyze-plan once to start the record."
   next: "This run was mode `{{mode}}`, change `{{active_change}}` (empty on the bootstrap path). BOOTSTRAP → /appweaver build → analyze-slice → run. DELTA → /appweaver build → analyze-slice-delta {{active_change}} → finalize-delta → analyze-slice → close-delta, with the change still OPEN throughout — compile first, then analyze-slice-delta verifies that every element the delta plans marked ADDED or MODIFIED is actually in the code with a paired test (the gate that catches a lane you declined at the prompt above), then finalize-delta merges it into spec.md + the context's domain-model.md while leaving it open, analyze-slice verifies the slice against those merged masters while a red result is still recoverable, and close-delta LAST archives the change and bumps the version."

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

@@ -9,8 +9,8 @@
 #   1. FEATURE MAP — a HIGH-LEVEL OKF discovery index of the features/aggregates the
 #      code contains (folders/concepts + a bounded-context map + the tech stack). It
 #      is a shallow map to pick from, NOT a deep reverse — the deep per-feature
-#      reverse (spec.md + design.md) is /appweaver adopt, done just-in-time when
-#      you are about to develop that feature.
+#      reverse (spec.md + the context's domain-model.md + the lane plans) is
+#      /appweaver adopt, done just-in-time when you are about to develop that feature.
 #
 #   2. GOVERNANCE SCAFFOLD — the PROJECT-level governing tier, established once from
 #      the whole-repo vantage so forward development is consistent from the first
@@ -123,7 +123,7 @@
 
 name: aw-spec-onboard
 description: Onboard an existing codebase for brownfield DEVELOPMENT — a deterministic whole-repo scan produces a high-level OKF feature map (folders/concepts) PLUS the project-level governance scaffold (split constitution + guardrails/projects/brf-<domain>/ with its DOMAIN rule files at domain/ + domain-rule-bindings + code-derived TECHNICAL rule files at service/ + tech-rule-bindings + activated domain), all provisional-from-scan and refined per slice by adopt. Where the scan finds a frontend lane in the CODE, it also authors that lane's half — constitution.ui.md (UX-*) — and its code-derived rule files at brf-<domain>/frontend/, mapped under `## /aw-spec-ui-constitution`; a backend-only repo gets none of it. Every rule tier is reverse-engineered from the CODE alone (never a greenfield rule file), evidenced-only, and WIRED per-workflow so the whole forward pipeline AND adopt govern against THIS codebase — never a greenfield fallback. It also reverse-engineers the repo's own technical structure into a project-specific design + delta-design template pair, installed as the project template overrides, and — where the lane exists — the frontend lane's own pair from the UI source. Every authoring step is shaped by a NEUTRAL rev-templates skeleton; no greenfield constitution, rule file or document template is ever placed in context. Accepts an optional concerns list to look for (onboard decides which are actually present). Reads any declared lane, never writes one. No migration content; never modifies source.
-version: 1.6.0
+version: 1.7.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -405,8 +405,9 @@ workflow:
 
       THIS IS A MAP, NOT A DEEP REVERSE. Keep every feature concept SHALLOW — enough
       to recognize and pick the feature to develop next. The deep per-feature reverse
-      (spec.md + design.md) is /appweaver adopt, run just-in-time when a feature is
-      about to be developed. Do NOT deep-model invariants/behaviour here.
+      (spec.md + the context's domain-model.md + the lane plans) is /appweaver adopt, run
+      just-in-time when a feature is about to be developed. Do NOT deep-model
+      invariants/behaviour here.
 
       Read the substrate first. Its `aggregate_signals` are CANDIDATE feature roots,
       each with its files grouped by layer plus detected entities; `ui_attribution`
@@ -648,8 +649,8 @@ workflow:
           charter; a later step in this same run authors it, so wire the bullet now), then the
           domain identity/regulatory/interop files → domain principles.
         - `## /aw-spec-specify`      — the FULL domain set (specify models the domain, lifts CN-/DC-/IC-).
-        - `## /aw-spec-plan`       — `_None — design loads no domain file. Domain reaches design only through the spec._`
-        - `## /aw-spec-implement`    — `_None — implement loads no domain file. Domain reaches implement only through design.md._`
+        - `## /aw-spec-plan`       — `_None — plan loads no domain file. Domain reaches plan through the spec and the context's domain-model.md._`
+        - `## /aw-spec-implement`    — `_None — implement loads no domain file. Domain reaches implement through the lane plans and the context's domain-model.md._`
         - `## /aw-spec-gate`         — the conformance-checklist set (the *.domain.md files).
       Each bullet is a workspace-relative path `- guardrails/projects/{{domain_slug}}/domain/<file>`.
       Write ONLY inside guardrails/projects/{{domain_slug}}/ (domain/ + the map). Report the
@@ -1415,7 +1416,13 @@ workflow:
   # override_active ⇒ design_mode == bootstrap_bf) then authors EVERY new feature against the
   # as-built architecture, and a CHANGE authors its delta-design against the SAME code-derived
   # sections (cr-setup scaffolds the delta from resolve_template("delta-design-template") ⇒
-  # the override) — no adopt required, consistent with the master design.md adopt emits.
+  # the override) — no adopt required, consistent with the backend-plan.md adopt emits.
+  #
+  # THE TEMPLATE IDENTIFIERS KEEP THE `design-template` SPELLING DELIBERATELY. The DOCUMENTS
+  # are backend-plan.md / frontend-plan.md now; the template NAMES are not, because a repo
+  # that already ran onboard carries its override at overrides/design-template.md and
+  # renaming the identifier would make that file stop resolving — silently falling back to
+  # the kit's greenfield template and imposing a layering the codebase never chose.
   #
   # GROUNDED IN CODE + REVERSE-ENGINEERED FILES ONLY. The Part-1 OKF feature map is a SHALLOW
   # discovery index (by design — NOT a deep reverse), so it is NOT the authority: the section
@@ -1597,6 +1604,83 @@ workflow:
     on_empty: stop
     on_empty_message: "No delta-design template was written to .appweaver/templates/overrides/delta-design-template.md. Re-run onboard after confirming the design template override was generated."
 
+  # ═══════ CODE-DERIVED DOMAIN-MODEL TEMPLATE (the context's structure) ════════
+  # The same argument as the design pair, for the document that carries the DOMAIN. A
+  # bounded context's domain-model.md is where the aggregate root, its boundary, its
+  # entities and the TEXT of every BR-nnn live; `specify` fills it on the forward path and
+  # `adopt` fills it per reversed slice. Without a code-derived override both author
+  # against the kit's GREENFIELD model template, whose shape assumes a domain that was
+  # designed before it was built — the one assumption a brownfield repo is guaranteed to
+  # break.
+  #
+  # NOT GATED ON A LANE. The domain model is ubiquitous language and invariants, which a
+  # frontend-only project has as much as any other; WHERE an invariant is enforced is the
+  # backend plan's concern and is gated with the service block above.
+  #
+  # A TEMPLATE OF A TEMPLATE. What this writes is not a filled model — it is the project's
+  # domain-model TEMPLATE, keeping every [PLACEHOLDER] and authoring comment. What onboard
+  # replaces is the STRUCTURE, never the content, and it must name NO aggregate and NO
+  # entity: naming one would hand the downstream author the answer to the single question
+  # the reverse exists to ask the code.
+  - id: ctx_model_template
+    action: build_context
+    context:
+      - { path: "{{inventory_json}}" }                                              # PRIMARY: the COMPLETE deterministic substrate
+      - { path: .appweaver/orchestrator/rev-templates/domain-model-template.skeleton.md }  # SHAPE ONLY: the neutral bones + the pinned anchors
+      - { path: "{{constitution_domain_file}}", optional: true }                    # the reversed DOMAIN frame — vocabulary, not structure
+      - { path: "{{bundle_dir}}/aggregates/index.md", optional: true }              # SECONDARY (shallow): the bounded-context / feature map
+  - id: gen_model_template
+    action: agent_generate
+    tools: "Read,Write,Edit"
+    permission_mode: acceptEdits
+    task: |
+      REVERSE-ENGINEER this repo's DOMAIN MODEL convention into a PROJECT-SPECIFIC
+      domain-model TEMPLATE and Write it to
+      .appweaver/templates/overrides/domain-model-template.md (create the overrides/ dir if
+      absent). It is a TEMPLATE — section headers with [PLACEHOLDER] tokens + authoring
+      HTML comments that `specify` (forward) and `adopt` (per reversed slice) fill per
+      context — NOT a filled model.
+
+      GROUND EVERYTHING IN THE CODE. Read REPRESENTATIVE source files; the OKF map in
+      context is a SHALLOW discovery index and corroborates, it does not decide.
+
+      KEEP THE PINNED ANCHORS from the skeleton in context — each is machinery something
+      keys on, not taste:
+      - `## Aggregate: <Name>` is the MERGE UNIT. finalize-delta merges a model delta one
+        such section at a time, so the heading FORM cannot be reshaped per project. Keep it
+        as ONE repeatable block.
+      - `### Invariants` carries stable BR-nnn ids — specs cite them and the conformance
+        gates trace them, so the id class cannot be renamed.
+      - `**Serving specs**:` is what makes a cross-spec aggregate visible from the model
+        side; keep it.
+      - The Change History table is the model's version ledger. close-delta appends to it
+        and stamps the context version; the model never writes its own.
+
+      WHAT YOU MAY ADAPT is everything else: which subsections an aggregate section carries
+      and what they are CALLED, in this codebase's own vocabulary. If the code expresses
+      structure through something it names differently, template THAT and say in a comment
+      which code paths evidence it.
+
+      NAME NO AGGREGATE, NO ENTITY AND NO TECHNOLOGY. Every [BRACKET] token stays a token.
+      Write the authoring comments so the downstream author derives from the code the way
+      the skeleton's BROWNFIELD DERIVATION note describes — aggregate roots from the types
+      referenced by id but never navigated into and the transaction boundaries the
+      persistence layer commits; entity vs value object by IDENTITY; invariants from the
+      guards and the persistence constraints, recording that the CODE is their current
+      authority; the ubiquitous language from the names the code actually uses, recording
+      BOTH where code and business disagree rather than silently picking one.
+
+      Write ONLY the override file; modify no source. Report the file written and the
+      structural choices you derived, with the code paths that evidence them.
+    outputs:
+      - { name: model_template_files, from: "$.files" }
+
+  - id: verify_model_template
+    action: verify_context
+    require_non_empty: model_template_files
+    on_empty: stop
+    on_empty_message: "No domain-model template was written to .appweaver/templates/overrides/domain-model-template.md. Without it every reversed slice authors its aggregate against the kit's GREENFIELD model template, whose shape assumes a domain designed before it was built. Ensure the scan substrate (inventory_json) is present and re-run."
+
   # ═══════ UI DESIGN TEMPLATES (frontend lane only) — the LANE's own pair ═══════
   # The lane's twin of the two steps above, on the same terms: reverse-engineered from
   # the UI SOURCE, shaped by a NEUTRAL skeleton, installed in the project override slot
@@ -1820,6 +1904,7 @@ outputs:
   delta_design_template_override: ".appweaver/templates/overrides/delta-design-template.md"
   design_template_files: "{{design_template_files}}"
   delta_design_template_files: "{{delta_design_template_files}}"
+  model_template_files: "{{model_template_files}}"   # the context's domain-model template — not lane-gated
   # The lane's own template pair. Empty on a backend-only repo — no lane, no files.
   ui_design_template_files: "{{ui_design_template_files}}"
   ui_delta_design_template_files: "{{ui_delta_design_template_files}}"

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

@@ -85,7 +85,7 @@
 
 name: aw-spec-plan
 description: "Author the feature's lane plans from the spec and the bounded context's domain model — backend-plan.md when a backend lane is declared, frontend-plan.md when a frontend lane is, both when both are. Lanes come from .appweaver/stacks.json, so one command covers backend-only, frontend-only and full-stack projects; the former separate design-ui command is folded in. It ASKS what it is planning, the way implement asks what it is building: the master (`main`), one of the OPEN CHANGES, or a new plan-only change for a refactor with no spec delta — the argument doubles as the answer, and the menu appears only once a master exists, so a first run bootstraps with no prompt. `main` on a feature that already has masters RE-DERIVES them from the merged spec.md + domain-model.md — the operation finalize-delta's contract assumes when it merges a change's spec and model halves and no lane plan — and is confirmed before it rewrites anything. A change instead gets delta-backend-plan.md / delta-frontend-plan.md inside changes/<CR-id>/ while the masters stay untouched, written against the effective model (the master model, the change's own model delta, and the pending model deltas of LOWER waves, which are its predecessors) and against the feature's real source files from its OKF concept. Master authoring is template-driven: the kit's templates by default, or the code-derived as-built structure when onboard installed an override. Authoring only — a master gates at analyze-plan; a change ships through the CR chain."
-version: 5.0.0
+version: 5.1.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -200,18 +200,21 @@ workflow:
   #    project's standards are exactly what they were before the two commands merged.
   #    No blocking gate: an unconfigured project soft-continues (the constitutions still
   #    carry each lane's ratified base).
+  #
+  #    ONLY THE BACKEND'S RULES LOAD HERE. The frontend's used to load alongside them,
+  #    before either lane authored anything, and sticky standards only accumulate — so the
+  #    service plan was authored with `## /aw-spec-plan-ui` in its envelope and the
+  #    experience plan with the service set. Each prompt names its lane, but it said so
+  #    inside an envelope that contradicted it. The UI set now loads at the frontend
+  #    boundary instead, with `replace`, in both places a frontend document is authored:
+  #    tech_select_ui_master before the master frontend sections, and the delta-plan
+  #    module's own swap before the frontend delta plan.
   - id: tech_select
     condition: "{{be_declared}} == true"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
     with: { command: aw-spec-plan }
 
-  - id: tech_select_ui
-    condition: "{{fe_declared}} == true"
-    action: include
-    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-plan-ui }
-
   # 2. Resolve the current feature and require its spec.
   - id: feature_paths
     action: execute_script
@@ -722,6 +725,23 @@ workflow:
         (the spec ids and BR-nnn that drove it). Do NOT invent a version number — the
         version spine belongs to close-delta.
 
+  # ══════════════ THE LANE SWAP — the frontend's rules replace the backend's ═══
+  # Both tech-select includes used to run up at step 4, before either lane authored
+  # anything, and sticky standards only accumulate — so on a full-stack run the backend
+  # plan was authored with `## /aw-spec-plan-ui` in its envelope and the frontend plan with
+  # the service set. Each prompt names its lane, but it did so inside an envelope that
+  # contradicted it, and the envelope is the half the model cannot argue with.
+  #
+  # `fe_mode != skip` is what makes this the MASTER path's swap and not the delta path's:
+  # fe_mode is only set to a real mode by the master branches above, so on a `plan CR-…`
+  # run this does not fire and the delta module below does its own swap at its own
+  # frontend boundary.
+  - id: tech_select_ui_master
+    condition: "{{fe_mode}} != skip"
+    action: include
+    module: .appweaver/orchestrator/modules/tech-select.orch.yaml
+    with: { command: aw-spec-plan-ui, replace: "true" }
+
   # ═══════════ FRONTEND LANE — bootstrap, greenfield experience template ═══════
   # The experience twin of the service plan, and the MEDIATOR between spec.md and the
   # frontend code. Its sections are the experience, not the four clean-architecture
@@ -993,7 +1013,14 @@ workflow:
       - { name: wave,              from: "$.wave" }
       - { name: predecessor_files, from: "$.predecessor_files" }
       - { name: predecessor_count, from: "$.predecessor_count" }
+      - { name: predecessor_ids,   from: "$.predecessor_ids" }
       - { name: sibling_count,     from: "$.sibling_count" }
+      - { name: sibling_ids,       from: "$.sibling_ids" }
+      # Predecessors AND siblings in one list: the delta plan is authored against both, and
+      # a build_context takes a single `context_from:` variable. Which entries are which is
+      # carried by predecessor_ids / sibling_ids, because the planner's licence over the two
+      # is opposite — a predecessor may be built on, a sibling may only be designed around.
+      - { name: related_docs,      from: "$.related_docs" }
 
   # Author that change's delta plans — one per declared lane whose MASTER exists, inside
   # changes/<CR-id>/ beside its delta-spec. The masters are left UNTOUCHED; the change