aw-spec-cli 0.1.20 → 0.1.21

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.)"