aw-spec-cli 0.1.28 → 0.1.30

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

@@ -0,0 +1,104 @@
+# =============================================================================
+# aw-spec-select-lane (orchestrator) — choose the lane THIS DEVELOPER works on
+#
+# stacks.json says which lanes the project has. .appweaver/lane.json says which of them
+# the developer on this machine is working on: `backend`, `frontend` or `both`. It is not
+# committed, so a backend developer and a frontend developer on one repository each keep
+# their own, and each can work on their lane at a different time from the other.
+#
+# select-stack writes the default — both when both lanes are declared, otherwise the one
+# that is — and a clone without the file reads that same default. Run this command only
+# to narrow it: a developer who builds one lane picks it once, and every later command
+# follows it until it is changed again.
+#
+# WHAT THE CHOICE CHANGES. plan, analyze-plan, implement, build and analyze-slice WRITE
+# only the working lane — they plan it, gate it, generate it, compile it and test it — and
+# still READ the other lane where they need it: a frontend plan binds to the backend
+# plan's published surface, which the backend developer owns. specify, finalize-delta and
+# close-delta do NOT follow it: the spec is written whole, from its rules and standards,
+# and a change merges and closes with whatever its lanes have delivered.
+#
+# THE OPTIONS COME FROM stacks.json. Both lanes declared → backend, frontend and both.
+# One lane declared → that lane only, picked without a question (there is nothing to
+# choose). No lane declared → stop, naming select-stack.
+#
+# ZERO LLM: two scripts, one gate and one select.
+#
+# Run (interactive via launcher):
+#   /appweaver select-lane              # list the lanes and pick one
+#   /appweaver select-lane frontend     # pick directly (backend | frontend | both)
+# Headless:
+#   --select select_lane=<option line>
+# =============================================================================
+
+name: aw-spec-select-lane
+description: Choose the lane this developer works on — backend, frontend or both — and store it in .appweaver/lane.json, which is not committed, so each developer keeps their own. The options come from the stacks declared in .appweaver/stacks.json, all three when both lanes are declared and only the declared one otherwise. plan, analyze-plan, implement, build and analyze-slice then write only that lane while still reading the other; specify, finalize-delta and close-delta do not follow it. select-stack writes the default (every declared lane); run this to narrow it.
+version: 1.0.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional working lane to set directly — backend, frontend or both. Only the whole word counts, and only a lane the declared stacks offer; anything else shows the list.
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+workflow:
+
+  # 1. The answers the declared stacks offer, the current choice, and the argument
+  #    matched against them as a whole word.
+  - id: list_lanes
+    action: execute_script
+    script: { ref: actions }
+    subcommand: lane-select
+    args: ["--preselect", "{{USER_INPUT}}"]
+    outputs:
+      - { name: lane_options,  from: "$.select_options" }
+      - { name: lane_count,    from: "$.option_count" }
+      - { name: lane_current,  from: "$.lane" }
+      - { name: lane_source,   from: "$.source" }
+      - { name: lane_match,    from: "$.preselect" }
+
+  # 2. No declared lane means nothing to work on.
+  - id: guard_no_lanes
+    action: verify_context
+    require_non_empty: lane_options
+    on_empty_message: >
+      No lane is declared in .appweaver/stacks.json, so there is no lane to work on.
+      Run /appweaver select-stack first and declare the backend stack, the frontend
+      stack, or both.
+    on_empty: stop
+
+  # 3. Choose. A whole-word argument selects directly; one declared lane is selected
+  #    without a question.
+  - id: select_lane
+    action: user_select
+    prompt: "Which lane are you working on? You are on `{{lane_current}}` now (from {{lane_source}}). The commands that plan, gate, generate, build and test write only this lane, and still read the other one:"
+    options_from_variable: lane_options
+    preselect_from: lane_match
+    single_option_confirm: true
+    outputs:
+      - { name: chosen, from: selection }
+
+  # 4. Persist it.
+  - id: set_lane
+    action: execute_script
+    script: { ref: actions }
+    subcommand: lane-select
+    args: ["--lane", "{{chosen}}"]
+    outputs:
+      - { name: working_lane,  from: "$.lane" }
+      - { name: working_kinds, from: "$.kinds" }
+      - { name: lane_file,     from: "$.path" }
+
+outputs:
+  working_lane: "{{working_lane}}"
+  working_kinds: "{{working_kinds}}"
+  lane_file: "{{lane_file}}"
+  note: "Working lane `{{working_lane}}` stored in {{lane_file}}. The file is not committed — it is this developer's choice, and another developer on the same repository keeps their own. From now on plan, analyze-plan, implement, build and analyze-slice write only the working lane: they plan it, gate it with its own receipt, generate it, compile it and test it. They still READ the other lane where they need it — a frontend plan binds to the operation ids the backend plan publishes. specify writes the whole spec whatever lane is chosen, and finalize-delta and close-delta merge and close a change with whatever its lanes have delivered. Re-running /appweaver select-stack resets the working lane to every declared lane."
+  next: "Run the lane's flow on the active feature: /appweaver plan → analyze-plan → implement → build → analyze-slice. Switch lanes any time with /appweaver select-lane backend | frontend | both."

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

@@ -34,6 +34,11 @@
 # lane a person already declared. Every other workflow calls `lane-resolve` to read
 # and `lane-verify` to gate, and neither can write.
 #
+# IT ALSO RESETS THE WORKING LANE. .appweaver/lane.json says which declared lanes the
+# developer on this machine works on — not committed, one per developer. Declaring the
+# lanes writes its default: `both` when both lanes are declared, otherwise the one that
+# is. /appweaver select-lane narrows it afterwards, for a developer who works on one lane.
+#
 # WHY THE LANE ROOT FOLDER IS ASKED AND NOT INHERITED. A lane root folder is the subtree its lane
 # OWNS: the only place implement's lane for it may write, the directory its build and
 # run commands act on, and in brownfield the code onboard reads. A profile's default
@@ -60,8 +65,8 @@
 # =============================================================================
 
 name: aw-spec-select-stack
-description: Declare the project's lanes — each lane's STACK and its LANE ROOT FOLDER — and persist them to .appweaver/stacks.json, the single channel every later workflow resolves and gates on. The first command of both the greenfield and the brownfield sequence, and the sole writer of the lane model.
-version: 2.3.0
+description: Declare the project's lanes — each lane's STACK and its LANE ROOT FOLDER — and persist them to .appweaver/stacks.json, the single channel every later workflow resolves and gates on. The first command of both the greenfield and the brownfield sequence, and the sole writer of the lane model. It also writes this developer's working lane, .appweaver/lane.json, to its default — both lanes when both are declared, otherwise the one that is — which /appweaver select-lane narrows to one lane.
+version: 2.4.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -270,6 +275,17 @@ workflow:
       a service lane, a UI lane, or both.
     on_false: stop
 
+  # 10b. THE WORKING LANE starts at every declared lane. Written only once the declaration
+  #      is sound, so a run stopped above never leaves a lane.json naming lanes that were
+  #      not declared. A re-run resets it on purpose: the lanes it named may be gone.
+  - id: default_lane
+    action: execute_script
+    script: { ref: actions }
+    subcommand: lane-select
+    args: ["--default"]
+    outputs:
+      - { name: working_lane, from: "$.lane" }
+
   # 11. Two ordered sets per lane, because the engine has no conditionals in
   #     `outputs:`: state the declined case, then override it where a lane was
   #     actually declared.
@@ -316,5 +332,6 @@ outputs:
   api_detected: "{{api_detected}}"
   ui_detected: "{{ui_detected}}"
   prototype: "{{prototype}}"
-  note: "Lanes persisted to .appweaver/stacks.json. Each lane carries a STACK and a LANE ROOT FOLDER, and both are load-bearing. The LANE ROOT FOLDER is ownership: implement's service lane writes its code only under the service lane's and its frontend lane only under the UI lane's, build/test/run act on it, and onboard reverse-engineers out of it. Each lane also owns a TEST PATH, taken from its stack profile — tests/ beside a .NET src/, the lane root folder itself for a stack that keeps its tests inside — and implement writes the lane's tests there. Overlapping paths of either kind are refused here rather than discovered later as two generators writing one file. The build/test/run commands are project-supplied strings the engine shells out to, which is how it stays stdlib-only and stack-ignorant. api_detected / ui_detected report what this repo's own files pointed at, whether or not it was chosen, as '<stack> at <path>' — or 'nothing detected' on a greenfield repo with nothing to detect. A lane root folder that does not exist yet is NORMAL here and reported rather than refused: greenfield declares src/ before implement creates it. The on-disk check runs in the phases that read the subtree — implement, build, run and onboard all call lane-verify and STOP with the fix named. Declining a lane with (none) is a real declaration and removes any lane of that kind a previous run left behind; it is also what stops that lane's constitution half and rule files being authored. `prototype` is not a lane — it has a root and a run command so an operator can open it, and nothing else. Re-run this workflow any time to re-stack a lane, move a lane root folder, or drop a lane with (none); it is the only workflow that may write this file."
+  working_lane: "{{working_lane}}"   # this developer's working lane, written to .appweaver/lane.json (not committed)
+  note: "Lanes persisted to .appweaver/stacks.json. Each lane carries a STACK and a LANE ROOT FOLDER, and both are load-bearing. The LANE ROOT FOLDER is ownership: implement's service lane writes its code only under the service lane's and its frontend lane only under the UI lane's, build/test/run act on it, and onboard reverse-engineers out of it. Each lane also owns a TEST PATH, taken from its stack profile — tests/ beside a .NET src/, the lane root folder itself for a stack that keeps its tests inside — and implement writes the lane's tests there. Overlapping paths of either kind are refused here rather than discovered later as two generators writing one file. The build/test/run commands are project-supplied strings the engine shells out to, which is how it stays stdlib-only and stack-ignorant. api_detected / ui_detected report what this repo's own files pointed at, whether or not it was chosen, as '<stack> at <path>' — or 'nothing detected' on a greenfield repo with nothing to detect. A lane root folder that does not exist yet is NORMAL here and reported rather than refused: greenfield declares src/ before implement creates it. The on-disk check runs in the phases that read the subtree — implement, build, run and onboard all call lane-verify and STOP with the fix named. Declining a lane with (none) is a real declaration and removes any lane of that kind a previous run left behind; it is also what stops that lane's constitution half and rule files being authored. `prototype` is not a lane — it has a root and a run command so an operator can open it, and nothing else. Re-run this workflow any time to re-stack a lane, move a lane root folder, or drop a lane with (none); it is the only workflow that may write this file. It also wrote .appweaver/lane.json — this developer's WORKING lane, set to {{working_lane}} — which is not committed: each developer keeps their own. A developer who works on one lane runs /appweaver select-lane, and from then on plan, analyze-plan, implement, build and analyze-slice write only that lane while still reading the other one."
   next: "GREENFIELD: /appweaver foundation → constitution → specify. The project rules live in guardrails/project-specific/, which .appweaver/domain.json names by default — fill in its rule files and its two maps; /appweaver select-domain switches to another project folder under guardrails/ when you keep more than one. On a project with no specs yet, constitution creates the default bounded context MainContext and its feature CoreFeature and makes both active; to use your own names, run /appweaver select-bounded-context <Name> and then /appweaver select-feature <Name> before specify. Once any bounded context exists, select-feature refuses to run until one is selected. foundation scaffolds every lane declared here in one run, backend then frontend — from a verified pack, from a spec the agent builds the project from, or skipped for a lane whose code already exists — and a spec build follows the technical rules the active project maps under `## /aw-spec-foundation-backend` and `## /aw-spec-foundation-frontend`. BROWNFIELD: /appweaver inventory — it scans the lane root folders declared here and proposes the bounded contexts and features as specs/proposed-inventory.md; edit that map, run /appweaver inventory apply, then /appweaver onboard <Context> once per bounded context, which reverse-engineers the governance out of the same lane root folders and activates it: onboard creates guardrails/brf-<domain>/ from the code and names it in .appweaver/domain.json. Run this workflow FIRST in either sequence: foundation scaffolds into the lane root folders declared here, constitution reads the declaration to decide which halves to author, and inventory and onboard read it to decide what to scan."

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

@@ -41,6 +41,12 @@
 # defaults a new delta to the wave already in flight (parallel by default); `cr-wave`
 # raises one that turns out to build on another.
 #
+# EACH CHANGE RECORDS ITS LANES. Opening a change asks which lanes it touches — both, the
+# default, or one of them, from the stacks declared — and stamps the answer on the
+# delta-spec's **Lanes** line. The spec is still written whole: the answer says which lanes
+# plan and build the change, never what the change requires. Like the rest of specify it
+# does not follow the developer's working lane (.appweaver/lane.json).
+#
 # EVERY DELTA STAGE NOW ASKS WHICH CHANGE. plan, analyze-plan-delta, implement,
 # recall-delta, finalize-delta and close-delta all list what is open, ask, and activate the
 # answer, with a bare CR id as the argument doubling as the answer. None of them takes
@@ -74,8 +80,8 @@
 # =============================================================================
 
 name: aw-spec-specify
-description: Author the ACTIVE feature's specification AND its bounded context's domain model, together. The aggregate root, its entities, events and invariants (BR-n) live in specs/<Context>/domain-model.md — the one canonical definition every spec in the context cites by id and never restates. First call writes the master spec (US-1) plus the master model; a later call opens its OWN change (many may be open at once) and writes that change's delta-spec and delta-domain-model, leaving both masters untouched for finalize-delta to merge. Each change carries a WAVE — deltas sharing one are independent and developable in parallel, a higher wave is implemented after the lower ones land — and its model delta sits beside the master so every other open delta can see it while being authored. Spec phase only — plan/design is separate.
-version: 3.5.0
+description: Author the ACTIVE feature's specification AND its bounded context's domain model, together. The aggregate root, its entities, events and invariants (BR-n) live in specs/<Context>/domain-model.md — the one canonical definition every spec in the context cites by id and never restates. First call writes the master spec (US-1) plus the master model; a later call opens its OWN change (many may be open at once) and writes that change's delta-spec and delta-domain-model, leaving both masters untouched for finalize-delta to merge. Opening a change asks which lanes it touches — both by default — and records the answer on the delta-spec's **Lanes** line; the spec is written whole either way. Each change carries a WAVE — deltas sharing one are independent and developable in parallel, a higher wave is implemented after the lower ones land — and its model delta sits beside the master so every other open delta can see it while being authored. Spec phase only — plan/design is separate.
+version: 3.6.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -121,6 +127,8 @@ vars:
   cr_dir: ""                 # set on the DELTA path only — changes/<cr-id>/
   delta_model: ""            # set on the DELTA path only — <context>/domain-model.<cr-id>.delta.md
   wave: ""                   # set on the DELTA path only — the parallel-development level
+  change_lanes: ""           # DELTA path only — the answer to "which lanes does this change touch?"
+  change_lanes_csv: ""       # DELTA path only — what the **Lanes** line now records
   open_count: "0"            # how many changes are open on this feature after this call
   domain_model: ""           # the CONTEXT's canonical model — bound by context-paths
   pending_model_files: []    # every OTHER open delta's model change, for build_context
@@ -717,6 +725,20 @@ workflow:
     outputs:
       - { name: checklist_passed, from: "$.after_checked" }
 
+  # 7a. THE CHANGE'S LANES, written again now that the converge block is done with the
+  #     delta-spec. The delta-spec module stamped the answer before the document was
+  #     authored; the clarify and validation passes above rewrite that document whole, and
+  #     this puts the **Lanes** line back to the answer whatever they did to it.
+  - id: restamp_change_lanes
+    condition: "{{is_bootstrap}} == false"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: cr-lanes
+    args: ["--cr-id", "{{cr_id}}", "--feature-dir", "{{feature_dir}}", "--stamp", "--set", "{{change_lanes}}"]
+    outputs:
+      - { name: change_lanes_csv, from: "$.lanes_csv" }
+
   # 7b. THE FIRST DRAFT IS FINISHED — lower the marker. Placed HERE, after the converge
   #     block, because that is the last thing the bootstrap path does to the document: a
   #     run that died inside the checklist or the clarify loop left a spec.md that is
@@ -764,13 +786,14 @@ outputs:
   domain_model: "{{domain_model}}"
   delta_model: "{{delta_model}}"            # DELTA path only — this change's model half
   wave: "{{wave}}"                          # DELTA path only — its parallel-development level
+  change_lanes: "{{change_lanes_csv}}"      # DELTA path only — the lanes that plan and build it
   open_changes: "{{open_count}}"            # how many changes are now open on this feature
   version: "{{version}}"
   change_id: "{{cr_id}}"
   authored_document: "{{quality_target}}"   # spec.md (bootstrap) | delta-spec.md (delta)
   checklist_file: "{{checklist_file}}"
   checklist_quality: "{{checklist_passed}}/{{checklist_total}} items passing"
-  note: "Behaviour and structure were authored together: the spec says what the system must do, {{domain_model}} says what the domain IS. The aggregate root, its entities and its invariants (BR-n) live in the model and are cited from the spec by id — never restated there, because several specs act on one aggregate and a per-spec copy drifts. On the DELTA path neither master was touched: this run wrote changes/{{cr_id}}/delta-spec.md and {{delta_model}}, and that model delta sits BESIDE the master where every other open delta can see it while being authored. WAVE {{wave}} is its parallel-development level — deltas sharing a wave are independent, a higher wave is implemented only after the lower ones land. The wave is DERIVED from the model delta's `## Depends on`: one above the highest delta named there, stamped into both halves as soon as it was authored ({{wave_message}}). To move it, correct that section and re-run `.appweaver/scripts/bash/aw-spec-actions.sh cr-wave-derive --cr-id {{cr_id}} --stamp`; finalize-delta refuses a change whose wave contradicts it. {{open_count}} change(s) are open on this feature."
+  note: "Behaviour and structure were authored together: the spec says what the system must do, {{domain_model}} says what the domain IS. The aggregate root, its entities and its invariants (BR-n) live in the model and are cited from the spec by id — never restated there, because several specs act on one aggregate and a per-spec copy drifts. On the DELTA path neither master was touched: this run wrote changes/{{cr_id}}/delta-spec.md and {{delta_model}}, and that model delta sits BESIDE the master where every other open delta can see it while being authored. WAVE {{wave}} is its parallel-development level — deltas sharing a wave are independent, a higher wave is implemented only after the lower ones land. The wave is DERIVED from the model delta's `## Depends on`: one above the highest delta named there, stamped into both halves as soon as it was authored ({{wave_message}}). To move it, correct that section and re-run `.appweaver/scripts/bash/aw-spec-actions.sh cr-wave-derive --cr-id {{cr_id}} --stamp`; finalize-delta refuses a change whose wave contradicts it. The change's **Lanes** line records the lanes that plan and build it ({{change_lanes_csv}}); the spec was written whole either way. To change it, run `.appweaver/scripts/bash/aw-spec-actions.sh cr-lanes --cr-id {{cr_id}} --set both|backend|frontend`. {{open_count}} change(s) are open on this feature."
   # Both paths spell out their WHOLE remaining chain. The bootstrap path named only
   # `plan` and stopped there, which left a first greenfield run with no successor at
   # the exact point the delta path was fully documented.