aw-spec-cli 0.1.19 → 0.1.21

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

@@ -40,10 +40,10 @@
 # drift. What this stage must NOT do is hide that by merging a delta plan: the plan would
 # then agree with the spec without any run of `plan` ever having derived it.
 #
-# ✅ THE DETECTION IS BUILT (2026-09-14). analyze-plan leaves `.aw-plan-gate.json` when it
-# PASSES — the sha256 of spec.md, the context's domain-model.md and each lane plan it read —
-# and `implement` reads it through plan-gate-check before any lane generates, refusing a
-# master run whose plans are no longer the ones the gate passed. So after this merge the
+# ✅ THE DETECTION IS BUILT (2026-09-14). Every master-mode analyze-plan run leaves
+# `.aw-plan-gate.json` — the sha256 of spec.md, the context's domain-model.md and each lane
+# plan it read, and its verdict — and `implement` reads it through plan-gate-check before any
+# lane generates, refusing a master run whose plans are no longer the ones the gate checked. So after this merge the
 # plans are not merely "visibly behind": the next `implement` on the master path says so and
 # stops, naming `plan main`. A feature with no receipt has never been gated since the receipt
 # existed and is reported, never refused.
@@ -94,17 +94,33 @@
 #   REBASE. The delta carries the master version it was authored against (`**Base version**:`,
 #   stamped by cr-setup). If the master has moved, the delta's MODIFIED items name a BEFORE
 #   spec.md no longer says, and merging them is last-writer-wins over work that landed.
+#   cr-rebase runs FIRST and re-stamps that header — and `**Base context version**` — when
+#   the move is one this delta survives: the masters moved, and everything that landed in
+#   between touched OTHER aggregates than the ones this delta names. Nothing else in the kit
+#   could ever write those headers, so before this the only way past the refusal was a hand
+#   edit the authoring prompts forbid. Where a landed change DOES share an aggregate, the
+#   stamp is left alone and the refusal below names it.
 #
 #   MERGED-NOT-CLOSED. The masters can move WITHOUT the version moving, because this stage
-#   merges and close-delta bumps. In that window spec.md carries a change the number does not
-#   reflect, so a sibling sharing the same base_version compares EQUAL and would merge onto
-#   masters that had already shifted. The version alone is not a proxy for "the masters
-#   moved"; the id appearing in spec.md is the other half of the answer.
+#   merges and close-delta bumps. In that window the masters carry a change the number does
+#   not reflect, so a sibling sharing the same base_version compares EQUAL and would merge
+#   onto masters that had already shifted. The version alone is not a proxy for "the masters
+#   moved"; a Change History row naming the change is the other half of the answer. That test
+#   lives in aw-crstate — one definition for this fence, cr-recall-check and close-delta —
+#   and it reads the CR CELL of a row, not the id anywhere in the file, which used to fire on
+#   an id quoted in prose. It looks at the context model too, which every feature shares, so
+#   a SIBLING feature's merged-unclosed change is visible; a sibling counts only where it
+#   touched an aggregate this delta also names.
 #
 #   PREDECESSOR. A lower wave is committed to landing first, and `plan` put exactly those
-#   deltas in this one's context as the base it was planned on top of. `depends_on` is
-#   stamped nowhere, so the wave is the only dependency signal that exists — and it is the
-#   conservative one, since same-wave changes are independent by definition.
+#   deltas in this one's context as the base it was planned on top of. Same-wave changes are
+#   independent by definition, so the wave is the conservative signal.
+#
+#   DECLARED DEPENDENCIES vs THE WAVE. The wave is a number; `## Depends on` in the change's
+#   own delta documents is what that number is supposed to encode. specify derives the wave
+#   from that section, and this stage re-checks it (cr-wave-derive): a change naming a
+#   predecessor at the same or a higher wave contradicts itself, and the predecessor fence
+#   above — which sees only numbers — would let the two merge in either order.
 #
 # All three are RAISE-then-VERIFY and fail-closed: each flag is raised only by the good
 # state, so a check that did not run leaves the merge refused rather than waved through.
@@ -153,6 +169,17 @@ vars:
   downstream_csv: ""       # the blast-radius names, fed to the scoped fence's --also and shown to the human
   fence_ok: "true"         # default green so the gate is a no-op when nothing downstream
   gate_decision: "clean"   # audit: 'clean' unless a RED fence was deliberately overridden
+  # The change's own `## Depends on` vs its wave — the fence that keeps the number and the
+  # prose from drifting apart. Defaults green, so a run that cannot read them is not blocked.
+  wave_ok: "true"
+  wave_required: ""
+  wave_message: ""
+  # The automatic rebase (cr-rebase). Defaults say "nothing moved, nothing stamped",
+  # so a step that could not run leaves the existing refusal to speak.
+  rebase_clean: "false"
+  rebase_stamped: ""
+  rebase_conflicts: ""
+  rebase_message: ""
   domain_model: ""            # specs/<Context>/domain-model.md — the second merge target
   domain_model_exists: "false"
   delta_model: ""             # specs/<Context>/domain-model.<id>.delta.md — the model half of the change
@@ -176,11 +203,12 @@ vars:
   merge_wave: "1"
   snapshot_dir: ""            # changes/<id>/pre-merge/ — the before-image recall-delta restores
   snapshot_count: "0"
-  # THE OKF OVERVIEW'S SUBJECT. The kit's working assumption is feature == aggregate; the
-  # Overview step is the one place it is load-bearing rather than cosmetic, because it
-  # selects a `## Aggregate:` section BY NAME. delta_aggregates is what the change's own
-  # model delta declares, so the common case is exact rather than assumed; it is empty for
-  # a behaviour-only change, which falls back to the feature name.
+  # THE OKF OVERVIEW'S SUBJECT. The Overview step selects a `## Aggregate:` section BY
+  # NAME, so it needs the aggregate, which is not always the feature: a feature that is
+  # one capability over a shared aggregate (PatientRegistration over Patient) has no
+  # section of its own name. delta_aggregates is what the change's own model delta
+  # declares; it is empty for a behaviour-only change, which falls back to the aggregate
+  # the feature answers for (feature-aggregates — the spec's Acts-on line).
   delta_aggregates: ""
   overview_scope: ""
   overview_section_ok: "false"
@@ -211,7 +239,7 @@ workflow:
     action: verify_context
     require_non_empty: feature_dir
     on_empty: stop
-    on_empty_message: "No active feature. Run /appweaver select-feature first (pick or create the aggregate, e.g. Order), then re-run finalize-delta."
+    on_empty_message: "No active feature. Run /appweaver select-feature first (pick or create the feature, e.g. Order or PatientRegistration), then re-run finalize-delta."
 
   - id: verify_spec
     action: verify_context
@@ -351,6 +379,28 @@ workflow:
   #     NO on_error: continue. A gate that cannot run must not be a gate that passes, and the
   #     raise-then-verify below is fail-closed for the same reason: each flag is raised ONLY
   #     by the good state, so a field that never arrived leaves it down and the merge refuses.
+  # AUTO-REBASE FIRST, and only where it is EARNED. `**Base version**` was written once by
+  # cr-setup and nothing could ever update it — every other site reads it, and every
+  # authoring prompt forbids the model from writing it — so a moved master left the operator
+  # hand-editing the delta-spec in the middle of an automated loop. cr-rebase re-stamps it
+  # (and `**Base context version**`, which until now nothing read at all) when the masters
+  # moved and NOTHING THAT LANDED IN BETWEEN touched the aggregates this delta names: then
+  # the delta still describes the document it was written against, and the stamp is
+  # bookkeeping. A landed change sharing an aggregate, or one whose model delta cannot be
+  # read, leaves the stamp alone — and the refusal below fires with the overlap named.
+  # It runs BEFORE cr-merge-check so that check reads the stamp this step just settled.
+  - id: auto_rebase
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: cr-rebase
+    args: ["--cr-id", "{{active_change}}", "--feature-dir", "{{feature_dir}}", "--stamp"]
+    outputs:
+      - { name: rebase_clean,     from: "$.clean" }
+      - { name: rebase_stamped,   from: "$.stamped" }
+      - { name: rebase_conflicts, from: "$.conflict_ids" }
+      - { name: rebase_message,   from: "$.message" }
+
   - id: merge_check
     action: execute_script
     script: { ref: actions }
@@ -375,7 +425,7 @@ workflow:
     action: verify_context
     require_true: rebase_ok
     on_false: stop
-    on_false_message: "finalize-delta REFUSED — change {{active_change}} needs a REBASE. It was authored against master version {{base_version}}, and the feature now stands at {{current_version}}: another change finalized and closed while this one was open. Its MODIFIED items name a BEFORE that spec.md no longer says, so merging now would overwrite work that already landed. Rebase: run /appweaver analyze-plan-delta {{active_change}} against the current master, fix what it reports, re-stamp the delta's `**Base version**:` to {{current_version}}, then re-run /appweaver finalize-delta {{active_change}}."
+    on_false_message: "finalize-delta REFUSED — change {{active_change}} needs a REBASE. It was authored against master version {{base_version}}, and the feature now stands at {{current_version}}: another change finalized and closed while this one was open. Its MODIFIED items name a BEFORE that spec.md no longer says, so merging now would overwrite work that already landed. The automatic re-stamp did not apply, because what landed in between touches this delta's own aggregates: {{rebase_message}}. Rebase for real: run /appweaver analyze-plan-delta {{active_change}} against the current master, fix what it reports — then `.appweaver/scripts/bash/aw-spec-actions.sh cr-rebase --cr-id {{active_change}} --stamp` re-stamps `**Base version**` and `**Base context version**` once the overlap with {{rebase_conflicts}} is resolved, and /appweaver finalize-delta {{active_change}} can run again."
 
   - id: merged_open_ok_raise
     condition: "{{has_merged_open}} == false"
@@ -385,7 +435,7 @@ workflow:
     action: verify_context
     require_true: merged_open_ok
     on_false: stop
-    on_false_message: "finalize-delta REFUSED — {{merged_open_ids}} has already been MERGED into spec.md but not yet CLOSED, so the masters carry it while the version still reads {{current_version}}. Change {{active_change}} was authored against those pre-merge masters and the version comparison cannot see the difference. Finish the merged change first: /appweaver analyze-slice then /appweaver close-delta {{merged_open_ids}}, which bumps the version — then rebase this one against the new number and re-run /appweaver finalize-delta {{active_change}}."
+    on_false_message: "finalize-delta REFUSED — {{merged_open_ids}} has already been MERGED into a master but not yet CLOSED, so the masters carry it while the version still reads {{current_version}}. That change may belong to ANOTHER feature in this context: domain-model.md is shared, so a sibling's merge moves a master this delta was authored against, and it is counted here when it touched an aggregate this delta also names. Change {{active_change}} was authored against those pre-merge masters and the version comparison cannot see the difference. Finish the merged change first: /appweaver analyze-slice then /appweaver close-delta {{merged_open_ids}}, which bumps the version — then rebase this one against the new number and re-run /appweaver finalize-delta {{active_change}}."
 
   - id: no_blockers_raise
     condition: "{{has_blockers}} == false"
@@ -395,7 +445,28 @@ workflow:
     action: verify_context
     require_true: no_blockers
     on_false: stop
-    on_false_message: "finalize-delta REFUSED — change {{active_change}} is at wave {{merge_wave}} and {{blocker_count}} open change(s) sit at a LOWER wave: {{blocker_ids}}. A lower wave is committed to landing FIRST, and this delta was planned with those in its context as the base it builds on — merging it now folds in behaviour that assumes a predecessor the masters do not yet carry. Merge and close the lower-wave change(s) first (/appweaver finalize-delta <CR-id> → analyze-slice → close-delta), then rebase and re-run this one. Same-wave changes are independent and are not counted here; if this delta does NOT in fact build on them, /appweaver cr-wave can correct its wave."
+    on_false_message: "finalize-delta REFUSED — change {{active_change}} is at wave {{merge_wave}} and {{blocker_count}} open change(s) sit at a LOWER wave: {{blocker_ids}}. A lower wave is committed to landing FIRST, and this delta was planned with those in its context as the base it builds on — merging it now folds in behaviour that assumes a predecessor the masters do not yet carry. Merge and close the lower-wave change(s) first (/appweaver finalize-delta <CR-id> → analyze-slice → close-delta), then rebase and re-run this one. Same-wave changes are independent and are not counted here; if this delta does NOT in fact build on them, correct its `## Depends on` section (naming only the deltas it truly builds on) and re-run /appweaver specify's wave derivation — `.appweaver/scripts/bash/aw-spec-actions.sh cr-wave-derive --cr-id {{active_change}} --stamp` applies it directly."
+
+  # THE DECLARED DEPENDENCIES AND THE WAVE MUST AGREE. The fence above orders changes by
+  # their wave NUMBER; this one checks that number against what the change's own documents
+  # SAY under `## Depends on`. Before this, the two could diverge silently: an author named
+  # a predecessor in prose, cr-setup left the wave at the predecessor's own level, and the
+  # fence above then read the two as independent and let them merge in either order.
+  - id: wave_declared_check
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: cr-wave-derive
+    args: ["--cr-id", "{{active_change}}"]
+    outputs:
+      - { name: wave_ok,       from: "$.ok" }
+      - { name: wave_required, from: "$.required_wave" }
+      - { name: wave_message,  from: "$.message" }
+  - id: require_wave_matches_depends
+    action: verify_context
+    require_true: wave_ok
+    on_false: stop
+    on_false_message: "finalize-delta REFUSED — change {{active_change}} contradicts its own `## Depends on`: {{wave_message}}. The blocker fence above compares wave NUMBERS, so it would let the two merge in either order and this delta could land before the change it says it builds on. Either raise this change to wave {{wave_required}} (`.appweaver/scripts/bash/aw-spec-actions.sh cr-wave-derive --cr-id {{active_change}} --stamp`, which reads the same section), or correct `## Depends on` in its delta documents if it does not in fact build on them."
 
   # 1c. DOWNSTREAM GATE (hard, with a REVIEWED override). Who depends on this aggregate —
   #     its OKF Cross-References, TRANSITIVELY (C→B→A all count) and placeholder-filtered
@@ -700,16 +771,15 @@ workflow:
   #     the context has no model: there would be nothing in context to distil, and a
   #     query with no source invents one. Best-effort; an empty answer is a no-op.
   # WHICH AGGREGATE SECTION(S) THIS CHANGE ACTUALLY TOUCHED, read off the model delta's
-  # own `## Aggregate:` headings rather than assumed from the feature name. The kit's
-  # working assumption is feature == aggregate, and it holds today — but the Overview step
-  # below is the one place that assumption is LOAD-BEARING rather than cosmetic: it selects
-  # a section by name, and a feature whose name is not an aggregate name selects nothing,
-  # producing an empty answer that the writer then declines. Driving it off the delta's
-  # declared aggregates makes the common case exact and the uncommon case visible.
+  # own `**Aggregates touched**:` header rather than assumed from the feature name. The Overview
+  # step below selects a section by name, and a feature whose name is not an aggregate
+  # name — one capability over a shared aggregate — selects nothing, producing an empty
+  # answer that the writer then declines. Driving it off the delta's declared aggregates
+  # makes a model change exact.
   #
   # A BEHAVIOUR-ONLY CHANGE HAS NO MODEL DELTA, so this reports none and the step falls
-  # back to the feature name — which is correct, not a degradation: there is no model
-  # change to distil and the concept's existing Overview stands.
+  # back to the aggregate the feature answers for — which is correct, not a degradation:
+  # there is no model change to distil and the concept's existing Overview stands.
   - id: cr_aggregates
     action: execute_script
     on_error: continue        # informational — a missing model delta is the ordinary case
@@ -720,9 +790,19 @@ workflow:
       - { name: delta_aggregates,     from: "$.aggregates_csv" }
       - { name: delta_aggregate_list, from: "$.aggregates" }
 
+  # The fallback subject: the aggregate this feature answers for, which is the feature
+  # itself on a 1:1 slice and the shared aggregate on a capability over one.
+  - id: feature_aggregates
+    action: execute_script
+    script: { ref: xref }
+    subcommand: feature-aggregates
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: owned_csv, from: "$.owned_csv" }
+
   - id: overview_scope_feature
     action: set
-    vars: { overview_scope: "{{feature}}" }
+    vars: { overview_scope: "{{owned_csv}}" }
   - id: overview_scope_delta
     condition: "{{delta_aggregates}} != "
     action: set
@@ -820,7 +900,11 @@ outputs:
   # the change by close-delta. What an un-merge would restore from.
   pre_merge_snapshot: "{{snapshot_dir}}"
   base_version: "{{base_version}}"
+  # What the automatic rebase did before the fence read the stamp — empty when the delta was
+  # already current, and the reason it could not when a landed change shared its aggregates.
+  rebased: "{{rebase_stamped}}"
+  rebase_note: "{{rebase_message}}"
   model_merged: "{{delta_model_exists}}"      # true ⇒ domain-model.md was the second target of this merge.
                                               # false = a behaviour-only change: the spec merge was the
                                               # whole merge, not a half of one.
-  next: "Delta MERGED into spec.md, and into the context's domain-model.md one aggregate section at a time where the change carried a model delta (model_merged={{delta_model_exists}} — false means a behaviour-only change, so the spec merge was the whole merge). The lane plans were NOT touched — they are DERIVED from these two masters, so backend-plan.md / frontend-plan.md now stand BEHIND the spec and model at their last authored content. That drift starts here and lasts until /appweaver plan main re-derives them, carrying the recorded decisions (DA-n) and workarounds (WA-n) forward and rewriting what the spec and model no longer support. analyze-plan is not what closes it and cannot repair it while this change is open: with a change open it runs READ-ONLY, reporting the drift into plan-analyze-report.md without rewriting either plan. The full gate — check, repair, stop — comes back once the last change is closed, so the order is close-delta, then plan main, then analyze-plan. OKF edges reconciled ({{xref_edge_count}} dep(s)), {{downstream_count}} downstream slice(s) fenced (gate: {{gate_decision}}). The concept Overview was distilled for aggregate(s) `{{overview_scope}}` — taken from what this change's model delta DECLARES it touched, not assumed from the feature name (empty on a behaviour-only change, which falls back to the feature). section_found={{overview_section_ok}}, written={{overview_written}}{{overview_reason}} — written=false is normal for a behaviour-only change (nothing to distil, the existing Overview stands), but section_found=false means domain-model.md has no `## Aggregate:` section under that name and the concept's Overview was left as it was: check that the feature name matches the aggregate the model defines. Change {{active_change}} is STILL OPEN and the version is still {{version}}. Next: /appweaver analyze-slice — it now reads masters that carry this change, and a red result is still recoverable because nothing has been archived. Then /appweaver close-delta archives the change and bumps the version."
+  next: "Delta MERGED into spec.md, and into the context's domain-model.md one aggregate section at a time where the change carried a model delta (model_merged={{delta_model_exists}} — false means a behaviour-only change, so the spec merge was the whole merge). The lane plans were NOT touched — they are DERIVED from these two masters, so backend-plan.md / frontend-plan.md now stand BEHIND the spec and model at their last authored content. That drift starts here and lasts until /appweaver plan main re-derives them, carrying the recorded decisions (DA-n) and workarounds (WA-n) forward and rewriting what the spec and model no longer support. analyze-plan is not what closes it and cannot repair it while this change is open: with a change open it runs READ-ONLY, reporting the drift into plan-analyze-report.md without rewriting either plan. The full gate — check, repair, stop — comes back once the last change is closed, so the order is close-delta, then plan main, then analyze-plan. OKF edges reconciled ({{xref_edge_count}} dep(s)), {{downstream_count}} downstream slice(s) fenced (gate: {{gate_decision}}). The concept Overview was distilled for aggregate(s) `{{overview_scope}}` — taken from what this change's model delta DECLARES it touched, not assumed from the feature name (empty on a behaviour-only change, which falls back to the aggregate the feature answers for). section_found={{overview_section_ok}}, written={{overview_written}}{{overview_reason}} — written=false is normal for a behaviour-only change (nothing to distil, the existing Overview stands), but section_found=false means domain-model.md has no `## Aggregate:` section under that name and the concept's Overview was left as it was: check that the spec's Acts on aggregate(s) line names an aggregate the model defines. Change {{active_change}} is STILL OPEN and the version is still {{version}}. Next: /appweaver analyze-slice — it now reads masters that carry this change, and a red result is still recoverable because nothing has been archived. Then /appweaver close-delta archives the change and bumps the version."

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

@@ -12,9 +12,26 @@
 # Interactive confirmations (proceed / overwrite / reference sample) ride the
 # checkpoint channel under EVERY strategy.
 #
+# A SCAFFOLD LANDS IN A LANE. The output directory is the SOURCE PATH of the lane being
+# scaffolded, read from .appweaver/stacks.json — never the repository root and never a
+# directory named on the command line. One bundle is one lane's project, so a repo with a
+# service and a UI is scaffolded by running this twice, once per lane, and each run's files
+# land in the subtree that lane owns. That is what makes every later phase's "write only
+# into your lane" rule true of the scaffold as well as of generated code: implement,
+# build, test and run all resolve the same path this unpacked into.
+#
+# The lane's TEST PATH is its second subtree, and for most backend stacks it is a sibling
+# of the source path rather than a directory inside it. A pack carrying its own test
+# project is unpacked like everything else and then has that tree lifted onto the lane's
+# test path — see .appweaver/scripts/python/aw-foundation.py for when that is a no-op.
+#
+# Lanes must therefore be declared FIRST: /appweaver select-stack is the sole writer of
+# stacks.json and the first command of both sequences.
+#
 # Launch via the parametric skill:  /appweaver foundation [strategy]
-#   Interactive (no args): LISTS the available foundations to pick from, then ASKS
-#   for the app (project) name — both deterministic, no LLM. Fast path still works:
+#   Interactive (no args): ASKS which lane to scaffold, LISTS the foundations available
+#   for that lane's ecosystem, then ASKS for the app (project) name — all deterministic,
+#   no LLM. Fast path still works:
 #     /appweaver foundation agent VerticalSlice AppWeaver.Health
 #
 # Headless:
@@ -25,14 +42,14 @@
 # =============================================================================
 
 name: aw-spec-foundation
-description: Scaffold a complete, compiling project — pick from the available foundation bundles and enter the app name, then unpack the verified bundle and rename its sentinel to your app name. Selection is zero-LLM (list + pick + ask).
-version: 1.1.0
+description: Scaffold a complete, compiling project INTO A DECLARED LANE — pick the lane, pick from the foundation bundles available for its ecosystem, enter the app name, and the verified bundle is unpacked into that lane's source path with its sentinel renamed. Selection is zero-LLM (list + pick + ask).
+version: 1.2.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
 inputs:
   user_input:
-    description: "Optional fast path: FoundationName [AppName] [OutputDirectory]. Omit to pick a foundation from the list and be asked for the app name."
+    description: "Optional fast path: FoundationName [AppName]. Omit to pick a foundation from the list and be asked for the app name. There is no output-directory argument — the scaffold goes into the chosen lane's source path."
     required: false
     bind: USER_INPUT
 
@@ -50,21 +67,83 @@ vars:
   stash_found: "false"   # true only when the reference flow stashed a DbContext
   app: ""                # resolved app name: fast-path 2nd token, else the ask below
   app_typed: ""          # app name entered interactively (empty on the fast path)
+  out_ok: "true"         # cleared when a third fast-path token names an output directory
 
 workflow:
 
-  # 1a. LIST the available foundations (deterministic foundations/<ecosystem>/<Name>/<Name>.pack.txt
-  #     scan — no LLM), narrowed to the ecosystems the declared lanes belong to. A
-  #     bundle is a whole compiling project in one ecosystem's build system, so the
-  #     list a Spring repo is shown and the list a .NET repo is shown are different
-  #     lists; `all_foundations` keeps the unfiltered set for the gate message below.
-  #     A direct "Foundation App [out]" argument is parsed here too as an optional
-  #     fast path (preselect_name / preselect_app / out_dir).
+  # 0a. THE LANE MODEL, which is where this scaffold is going. Read-only: select-stack is
+  #     the sole writer, and a scaffold has no business declaring the lane it fills.
+  - id: lanes
+    action: execute_script
+    on_error: continue    # never crash raw on an absent stacks.json — the gate explains it
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: lane_options, from: "$.lane_options" }
+      - { name: lane_count,   from: "$.lane_count" }
+
+  - id: require_lanes
+    action: verify_context
+    require_non_empty: lane_options
+    on_empty: stop
+    on_empty_message: >
+      /appweaver foundation cannot run: no lane is declared in .appweaver/stacks.json.
+      A scaffold is unpacked into the SOURCE PATH of the lane it belongs to — that is what
+      keeps a project's files inside the subtree every later phase compiles, tests and
+      generates into — so there has to be a lane to scaffold before there is a scaffold.
+      Run /appweaver select-stack first: it declares each lane's stack and source path, and
+      is the first command of both the greenfield and the brownfield sequence.
+
+  # 0b. WHICH lane. One bundle is one lane's project, so a fullstack repo runs this once
+  #     per lane rather than unpacking a tree that spans both. A single declared lane
+  #     auto-confirms; the option carries its own explanation and resolves below.
+  - id: pick_lane
+    action: user_select
+    prompt: "Which lane is this scaffold for? The bundle is unpacked into that lane's source path, and its tests into the lane's test path — nothing lands outside them. Scaffold the other lane by running /appweaver foundation again."
+    options_from_variable: lane_options
+    single_option_confirm: true
+    outputs:
+      - { name: chosen_lane, from: selection }
+
+  # 0c. Resolve the chosen lane to the two paths this run writes into, plus the ecosystem
+  #     that narrows the bundle list. `lane-resolve` strips the option's label itself, so
+  #     the selection goes back in as the id it already carries.
+  - id: lane_target
+    action: execute_script
+    script: { ref: actions }
+    subcommand: lane-resolve
+    args: ["--id", "{{chosen_lane}}"]
+    outputs:
+      - { name: lane_found,     from: "$.found" }
+      - { name: lane_id,        from: "$.lane_id" }
+      - { name: lane_root,      from: "$.source_path" }
+      - { name: lane_test_path, from: "$.test_path" }
+      - { name: lane_ecosystem, from: "$.ecosystem" }
+      - { name: lane_language,  from: "$.language" }
+
+  - id: lane_resolved
+    action: verify_context
+    require_true: lane_found
+    on_false: stop
+    on_false_message: "No lane matches the selection `{{chosen_lane}}` in .appweaver/stacks.json. Re-run /appweaver select-stack to re-declare the lanes, then re-run foundation."
+
+  - id: lane_has_root
+    action: verify_context
+    require_non_empty: lane_root
+    on_empty: stop
+    on_empty_message: "Lane `{{lane_id}}` declares no source path in .appweaver/stacks.json, and the source path is where this scaffold is unpacked. Re-run /appweaver select-stack and give the lane the directory it owns."
+
+  # 1a. LIST the foundations available for THAT LANE's ecosystem (deterministic
+  #     foundations/<ecosystem>/<Name>/<Name>.pack.txt scan — no LLM). A bundle is a whole
+  #     compiling project in one ecosystem's build system, so a Node UI lane is not offered
+  #     a .NET bundle even in a repo that also declares a .NET service; `all_foundations`
+  #     keeps the unfiltered set for the gate message below. A direct "Foundation App"
+  #     argument is parsed here too as an optional fast path.
   - id: list_foundations
     action: execute_script
     script: { ref: actions }
     subcommand: foundation-list
-    args: ["--args", "{{USER_INPUT}}"]
+    args: ["--args", "{{USER_INPUT}}", "--ecosystem", "{{lane_ecosystem}}"]
     outputs:
       - { name: foundations,      from: "$.foundations" }
       - { name: foundation_count, from: "$.count" }
@@ -72,23 +151,41 @@ workflow:
       - { name: lane_ecosystems,  from: "$.lane_ecosystems" }
       - { name: preselect_name,   from: "$.preselect_name" }
       - { name: preselect_app,    from: "$.preselect_app" }
-      - { name: out_dir,          from: "$.out_dir" }
+      - { name: rejected_out,     from: "$.rejected_out" }
+
+  # 1b. A third fast-path token used to be an output directory. Refused by name rather
+  #     than ignored: silently dropping a path argument is how someone believes they
+  #     scaffolded a sandbox and finds they filled their service lane.
+  - id: out_dir_given
+    action: set
+    condition: "{{rejected_out}} != "
+    vars: { out_ok: "" }
+
+  - id: no_out_dir
+    action: verify_context
+    require_true: out_ok
+    on_false: stop
+    on_false_message: >
+      `{{rejected_out}}` was given as an output directory, and foundation has none to give.
+      A scaffold is unpacked into the source path of the lane it is for — here lane
+      `{{lane_id}}` at `{{lane_root}}` — so that everything it writes is inside the subtree
+      that lane owns. Re-run as `/appweaver foundation {{preselect_name}} {{preselect_app}}`.
+      To scaffold somewhere else, declare a lane there with /appweaver select-stack and
+      pick that lane.
 
   - id: have_foundations
     action: verify_context
     require_non_empty: foundations
     on_empty: stop
     on_empty_message: >
-      No foundation bundle is available for this repository. Bundles present:
-      {{all_foundations}}; the ecosystem(s) this repository declares in
-      .appweaver/stacks.json: {{lane_ecosystems}}. A foundation is a complete project in
-      one ecosystem's languages and build system, so one from another ecosystem is not a
-      scaffold for this repo — it is a second, foreign project beside it. Either add a
-      bundle under foundations/<ecosystem>/<Name>/<Name>.pack.txt for your stack (see the
-      pack scripts in that directory), or scaffold with the stack's own tooling (Spring
-      Initializr, `npm create`, `cargo new`, …) and declare the result with
-      /appweaver select-stack — implement generates INTO a project tree and does not
-      require that the kit be the thing that created it.
+      No foundation bundle ships for the `{{lane_id}}` lane's ecosystem ({{lane_ecosystem}}).
+      Bundles present: {{all_foundations}}. A foundation is a complete project in one
+      ecosystem's languages and build system, so one from another ecosystem is not a
+      scaffold for this lane — it is a second, foreign project inside it. Either add a
+      bundle under foundations/{{lane_ecosystem}}/<Name>/<Name>.pack.txt (see the pack
+      scripts in that directory), or scaffold `{{lane_root}}` with the stack's own tooling
+      (Spring Initializr, `npm create`, `cargo new`, …) — implement generates INTO a
+      project tree and does not require that the kit be the thing that created it.
 
   # 1b. PICK the foundation. A matching fast-path arg auto-selects; a lone
   #     foundation auto-confirms; otherwise the user chooses from the list.
@@ -128,14 +225,13 @@ workflow:
     action: execute_script
     script: { ref: actions }
     subcommand: foundation-locate
-    args: ["--name", "{{fname}}", "--app", "{{app}}", "--out", "{{out_dir}}"]
+    args: ["--name", "{{fname}}", "--app", "{{app}}", "--out", "{{lane_root}}"]
     outputs:
       - { name: locate_ok,  from: "$.ok" }
       - { name: locate_msg, from: "$.reason" }
       - { name: available,  from: "$.available" }
       - { name: fname,      from: "$.name" }
       - { name: app,        from: "$.app" }
-      - { name: out_dir,    from: "$.out_dir" }
       - { name: sentinel,   from: "$.sentinel" }
       - { name: file_count, from: "$.file_count" }
 
@@ -151,7 +247,9 @@ workflow:
     prompt: |
       Foundation: {{fname}} (sentinel {{sentinel}}, {{file_count}} files)
       App Name:   {{app}}
-      Output:     {{out_dir}}
+      Lane:       {{lane_id}} — {{lane_language}} ({{lane_ecosystem}})
+      Source:     {{lane_root}}          <- the whole bundle unpacks here
+      Tests:      {{lane_test_path}}     <- a test tree the bundle carries is lifted here
       Rename {{sentinel}} -> {{app}} (dotted/underscored/hyphen/lower forms).
       Unchanged: 'Projects' sample domain + AppWeaver.* framework packages. Proceed?
     options: ["yes", "no"]
@@ -169,7 +267,7 @@ workflow:
     action: execute_script
     script: { ref: actions }
     subcommand: foundation-unpack
-    args: ["--name", "{{fname}}", "--app", "{{app}}", "--out", "{{out_dir}}", "--dry-run"]
+    args: ["--name", "{{fname}}", "--app", "{{app}}", "--out", "{{lane_root}}", "--dry-run"]
     outputs:
       - { name: has_collisions, from: "$.has_collisions" }
 
@@ -193,9 +291,11 @@ workflow:
     action: execute_script
     script: { ref: actions }
     subcommand: foundation-unpack
-    args: ["--name", "{{fname}}", "--app", "{{app}}", "--out", "{{out_dir}}", "--force", "{{overwrite}}"]
+    args: ["--name", "{{fname}}", "--app", "{{app}}", "--out", "{{lane_root}}", "--test-path", "{{lane_test_path}}", "--force", "{{overwrite}}"]
     outputs:
-      - { name: written, from: "$.written" }
+      - { name: written,       from: "$.written" }
+      - { name: tests_moved,   from: "$.tests_moved" }
+      - { name: tests_message, from: "$.tests_message" }
 
   # 5. Optional reference sample.
   - id: ask_reference
@@ -209,7 +309,7 @@ workflow:
     condition: "{{want_reference}} == yes"
     script: { ref: actions }
     subcommand: foundation-stash-dbcontext
-    args: ["--out", "{{out_dir}}"]
+    args: ["--out", "{{lane_root}}"]
     outputs:
       - { name: stash_found, from: "$.found" }
       - { name: db_context,  from: "$.dbcontext" }
@@ -220,7 +320,7 @@ workflow:
     condition: "{{want_reference}} == yes"
     script: { ref: actions }
     subcommand: foundation-unpack
-    args: ["--name", "{{fname}}", "--app", "{{app}}", "--out", "{{out_dir}}", "--reference"]
+    args: ["--name", "{{fname}}", "--app", "{{app}}", "--out", "{{lane_root}}", "--test-path", "{{lane_test_path}}", "--reference"]
     outputs:
       - { name: ref_written, from: "$.written" }
 
@@ -248,7 +348,7 @@ workflow:
     action: execute_script
     script: { ref: actions }
     subcommand: foundation-verify
-    args: ["--out", "{{out_dir}}", "--sentinel", "{{sentinel}}"]
+    args: ["--out", "{{lane_root}}", "--sentinel", "{{sentinel}}"]
     outputs:
       - { name: clean,   from: "$.clean" }
       - { name: residue, from: "$.residue" }
@@ -256,10 +356,14 @@ workflow:
 outputs:
   foundation: "{{fname}}"
   app: "{{app}}"
-  output_dir: "{{out_dir}}"
+  lane: "{{lane_id}}"
+  source_path: "{{lane_root}}"
+  test_path: "{{lane_test_path}}"
   files_written: "{{written}}"
+  tests_moved: "{{tests_moved}}"
+  tests_note: "{{tests_message}}"
   reference_files: "{{ref_written}}"
   sentinel_clean: "{{clean}}"
   sentinel_residue: "{{residue}}"
-  note: "Foundation scaffolded into {{out_dir}} ({{written}} file(s), sentinel renamed to {{app}}). Configure your AppWeaver.* NuGet feed and run the AppHost to confirm the scaffold starts before building on it."
-  next: "/appweaver select-feature   (pick the feature to build; every stage from specify onward reads that active feature and stops without it. If this workspace has governed projects under guardrails/projects/, run /appweaver select-domain first — it is one-time and optional.)"
+  note: "Foundation scaffolded into the {{lane_id}} lane at {{lane_root}} ({{written}} file(s), sentinel renamed to {{app}}); {{tests_message}}. Everything written is inside the subtree that lane owns, which is where implement generates and build/test/run act. Configure your AppWeaver.* NuGet feed and run the AppHost to confirm the scaffold starts before building on it."
+  next: "Another lane still to scaffold? Run /appweaver foundation again and pick it — one bundle fills one lane. Otherwise /appweaver select-feature (pick the feature to build; every stage from specify onward reads that active feature and stops without it. If this workspace has governed projects under guardrails/projects/, run /appweaver select-domain first — it is one-time and optional.)"