aw-spec-cli 0.1.32 → 0.1.34

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

@@ -16,7 +16,10 @@
 # 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.
+# and a change merges and closes with whatever its lanes have delivered. Brownfield adopt
+# does not follow it either: it reverses a feature once, every half its code has, because
+# it cannot run a second time for the other lane, so the other lane's developer finds
+# their plan already written.
 #
 # 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
@@ -32,8 +35,8 @@
 # =============================================================================
 
 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
+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, close-delta and brownfield adopt do not follow it. select-stack writes the default (every declared lane); run this to narrow it.
+version: 1.0.2
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -100,5 +103,5 @@ 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."
+  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 feature's API plan (api-plan.md) publishes, and never reads the backend plan. 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. Brownfield adopt reverses a feature once, every half its code has, whatever lane is chosen, so the other lane's developer finds their plan already written. 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

@@ -52,8 +52,15 @@
 # for the projects it matters most to. `lane-verify` runs the on-disk check, in the
 # phases that actually read the subtree — implement, build, run, onboard.
 #
-# ZERO LLM: scripts, two gates, two selects and two questions. No generation, no
-# rule resolution.
+# WHICH STACKS HAVE A RULE SET is said where the stack is chosen. Each menu's prompt
+# carries one line from `stack-rules` — the stacks the active project's technical map has
+# rule files for, complete or partial, and the ones it has none for — and a lane declared
+# on a stack whose rule set is missing or incomplete raises a warning. Every stack stays
+# selectable: one without a rule set runs on ai-rules.md and the technical constitution
+# (STACK-PROFILES.md §7), and the point is that the operator knows it before choosing.
+#
+# ZERO LLM: scripts, two gates, two warnings, two selects and two questions. No
+# generation; the rule report reads the map and the disk and loads nothing.
 #
 # Run (interactive via launcher):
 #   /appweaver select-stack                              # ask everything
@@ -66,7 +73,7 @@
 
 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. 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
+version: 2.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -85,6 +92,17 @@ scripts:
     sh:  .appweaver/scripts/bash/aw-spec-actions.sh
     ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
 
+vars:
+  api_rules_note: ""         # the menu's rule-set line for a backend stack (stack-rules)
+  api_rules_ok: "false"      # the declared service lane's stack has a complete rule set, or the
+                             # map names none for the lane — only stack-rules' own `ok` raises it
+  api_rules_warning: ""
+  api_rule_set: ""           # complete | partial | none | not-mapped; empty with no service lane
+  ui_rules_note: ""
+  ui_rules_ok: "false"
+  ui_rules_warning: ""
+  ui_rule_set: ""
+
 workflow:
 
   # ═══════════════ SERVICE LANE ═══════════════════════════════════════════════
@@ -118,11 +136,22 @@ workflow:
       stacks there), then re-run.
     on_empty: stop
 
+  # 2b. Which backend stacks the active project's technical map has rule files for, as
+  #     one line for the prompt. The option labels stay as stack-list wrote them, because
+  #     lane-declare matches a label back to its profile.
+  - id: api_rules
+    action: execute_script
+    script: { ref: actions }
+    subcommand: stack-rules
+    args: ["--kind", "backend"]
+    outputs:
+      - { name: api_rules_note, from: "$.note" }
+
   # 3. Choose the service stack. A matching id in USER_INPUT auto-selects, and so
   #    does a detected stack; a project with exactly one candidate auto-confirms.
   - id: select_api_stack
     action: user_select
-    prompt: "Select the API (backend) stack — it owns the service lane. This repo's own files point at: {{api_detected}}. A detected stack leads the list. (none) declares a project with no service lane at all, and stops the technical constitution half and the service rule files being authored:"
+    prompt: "Select the API (backend) stack — it owns the service lane. This repo's own files point at: {{api_detected}}. A detected stack leads the list. (none) declares a project with no service lane at all, and stops the technical constitution half and the service rule files being authored. {{api_rules_note}}"
     options_from_variable: api_options
     preselect_from: api_preselect
     single_option_confirm: true
@@ -180,6 +209,25 @@ workflow:
       - { name: api_test_path,   from: "$.test_path" }
       - { name: api_root_exists, from: "$.root_exists" }
 
+  # 6b. A service lane on a stack whose rule set is missing or incomplete is a supported
+  #     setup, said here once with what it means and how to change it. The run continues.
+  - id: api_rules_check
+    condition: "{{api_declared}}"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: stack-rules
+    args: ["--kind", "backend", "--declared"]
+    outputs:
+      - { name: api_rules_ok,      from: "$.ok" }
+      - { name: api_rules_warning, from: "$.warning" }
+      - { name: api_rule_set,      from: "$.verdict" }
+  - id: warn_api_rules
+    condition: "{{api_declared}}"
+    action: verify_context
+    require_true: api_rules_ok
+    on_false: continue
+    on_false_message: "{{api_rules_warning}}"
+
   # ═══════════════ UI LANE ════════════════════════════════════════════════════
 
   # 7. Candidates for the UI lane, same shape. The service lane is already declared
@@ -198,10 +246,20 @@ workflow:
       - { name: ui_detected,      from: "$.detected_summary" }
       - { name: ui_none_sentinel, from: "$.none_sentinel" }
 
+  # 7b. The UI stacks' rule sets, measured with the service lane just declared: a
+  #     frontend rule set can name a file per backend stack (its API integration).
+  - id: ui_rules
+    action: execute_script
+    script: { ref: actions }
+    subcommand: stack-rules
+    args: ["--kind", "frontend"]
+    outputs:
+      - { name: ui_rules_note, from: "$.note" }
+
   # 8. Choose the UI stack.
   - id: select_ui_stack
     action: user_select
-    prompt: "Select the UI (frontend) stack — it owns the web lane, and its root must not overlap the service lane's. This repo's own files point at: {{ui_detected}}. A detected stack leads the list. (none) declares a backend-only project, and stops the UI constitution half and the frontend rule files being authored:"
+    prompt: "Select the UI (frontend) stack — it owns the web lane, and its root must not overlap the service lane's. This repo's own files point at: {{ui_detected}}. A detected stack leads the list. (none) declares a backend-only project, and stops the UI constitution half and the frontend rule files being authored. {{ui_rules_note}}"
     options_from_variable: ui_options
     preselect_from: ui_preselect
     single_option_confirm: true
@@ -246,6 +304,23 @@ workflow:
       - { name: ui_test_path,   from: "$.test_path" }
       - { name: ui_root_exists, from: "$.root_exists" }
 
+  - id: ui_rules_check
+    condition: "{{ui_declared}}"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: stack-rules
+    args: ["--kind", "frontend", "--declared"]
+    outputs:
+      - { name: ui_rules_ok,      from: "$.ok" }
+      - { name: ui_rules_warning, from: "$.warning" }
+      - { name: ui_rule_set,      from: "$.verdict" }
+  - id: warn_ui_rules
+    condition: "{{ui_declared}}"
+    action: verify_context
+    require_true: ui_rules_ok
+    on_false: continue
+    on_false_message: "{{ui_rules_warning}}"
+
   # ═══════════════ CHECK + REPORT ═════════════════════════════════════════════
 
   # 10. Is what was just written sound? --allow-missing-root because a lane root folder
@@ -333,5 +408,7 @@ outputs:
   ui_detected: "{{ui_detected}}"
   prototype: "{{prototype}}"
   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."
+  api_rule_set: "{{api_rule_set}}"   # complete | partial | none | not-mapped — the service stack's rule set in the active project's map
+  ui_rule_set: "{{ui_rule_set}}"     # the same for the UI stack
+  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. api_rule_set / ui_rule_set say how much of each chosen stack's technical rule set the active project's map finds on disk — complete, partial, none, or not-mapped where the map names no stack folder for that lane. A stack with none runs on ai-rules.md and the technical constitution; a warning above says what to write to change that."
   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

@@ -81,7 +81,7 @@
 
 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. 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
+version: 3.7.1
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -131,6 +131,10 @@ vars:
   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
+  model_guard_ok: "false"    # model-guard-check's verdict on the bootstrap rewrite. DEFAULTS
+                             # TO REFUSE: only the check's own `ok` lets the run past the gate
+  model_guard_losses: ""     # what the rejected rewrite lost, one clause per item
+  model_guard_rejected: ""   # where the rejected rewrite was kept
   pending_model_files: []    # every OTHER open delta's model change, for build_context
   pending_count: "0"
   next_wave: "1"
@@ -443,6 +447,19 @@ workflow:
       - .appweaver/memory/constitution.domain.md
       - { path: .appweaver/memory/constitution.ui.md, optional: true }
 
+  # THE REWRITE IS CHECKED. The engine writes the agent's reply over the WHOLE model, and
+  # from a context's second feature on that file holds the aggregates, the BR-/XBR- rules
+  # and the ledger rows other features rely on. The snapshot copies it aside; the check
+  # after the step compares the two (python/aw-model-guard.py) and, on a loss, puts the
+  # model back and keeps the rewrite as domain-model.rejected.md. Template placeholders are
+  # not recorded, so a context's first feature is held to nothing but its Context version.
+  - id: boot_model_snapshot
+    condition: "{{is_bootstrap}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: model-guard-snapshot
+    args: ["--model", "{{domain_model}}"]
+
   - id: boot_model_generate
     condition: "{{is_bootstrap}} == true"
     action: agent_author
@@ -465,6 +482,12 @@ workflow:
         yet gets a new section. EXTEND the ubiquitous language. Do NOT rewrite, renumber
         or "tidy" what is already there — other specs cite those ids, and a renumbered BR
         breaks every citation silently.
+      - A SCRIPT COMPARES YOUR FILE WITH THE MODEL AS IT WAS, and puts the old one back if
+        any of these is gone: an `## Aggregate:` section under its name; a BR-n or XBR-n,
+        in the same section, with the same rule text, defined once; a name on an
+        aggregate's `Serving specs` line; a Ubiquitous Language term; a context the
+        Context Map names; a Change History row; the Context version. Add to any of them
+        freely; never remove, rename, renumber, move or reword one.
       - DDD IS THE RATIFIED MODELLING STANDARD (NON-NEGOTIABLE → the modelling-methodology
         standard in the sticky standards, wired per-project via tech-rule-bindings
         "## /aw-spec-specify", plus the domain's own DDD overlay): a consistent ubiquitous
@@ -481,6 +504,26 @@ workflow:
       - Do NOT write the Context version or the Change History version column — scripts
         stamp those. Fill the initial row's date and aggregate only.
 
+  - id: boot_model_check
+    condition: "{{is_bootstrap}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: model-guard-check
+    args: ["--model", "{{domain_model}}"]
+    outputs:
+      - { name: model_guard_ok,       from: "$.ok" }
+      - { name: model_guard_losses,   from: "$.losses_text" }
+      - { name: model_guard_rejected, from: "$.rejected" }
+
+  # On a stop the model is already restored, and the unfinished-first-draft marker is still
+  # up, so the re-run asks to re-author the draft.
+  - id: boot_model_guard
+    condition: "{{is_bootstrap}} == true"
+    action: verify_context
+    require_true: model_guard_ok
+    on_false: stop
+    on_false_message: "The domain model lost content other features rely on, so {{domain_model}} was put back as it was before this run. Lost: {{model_guard_losses}}. The rejected rewrite is kept at {{model_guard_rejected}} for inspection. Run /appweaver specify again and choose \"Re-author the first draft\"."
+
   # ═════════════════════════ DELTA — spec.md exists ═════════════════════════
   # A later requirement = a new user story on the SAME aggregate. Delegate to the
   # delta-spec module: it opens the change (cr-setup) and authors BOTH of the change's
@@ -797,4 +840,4 @@ outputs:
   # 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.
-  next: "/appweaver plan — BOOTSTRAP authors backend-plan.md from the spec + the domain model (plus frontend-plan.md where a UI lane is declared); a DELTA (this run opened change {{cr_id}}, wave {{wave}}) authors the delta plans for it. BOOTSTRAP then flows: plan → analyze-plan → implement → build → analyze-slice → run → deploy (analyze-plan is the spec↔plan gate and it repairs and stops only while NO change is open). A change instead flows: analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta (finalize-delta merges the delta into spec.md + domain-model.md — not the lane plans, which are derived from those two — but leaves the change open; analyze-slice verifies the slice against the merged master; close-delta archives the change and bumps the version). ⚠️ With more than one change open, plan, analyze-plan-delta and implement ASK which one they are for (pass the id as the argument to skip the prompt) and activate the answer; finalize-delta and close-delta still act on whichever change is active — so finish or close the others deliberately."
+  next: "/appweaver plan — BOOTSTRAP authors api-plan.md and backend-plan.md from the spec + the domain model (plus frontend-plan.md where a UI lane is declared); a DELTA (this run opened change {{cr_id}}, wave {{wave}}) authors the delta plans for it. BOOTSTRAP then flows: plan → analyze-plan → implement → build → analyze-slice → run → deploy (analyze-plan is the spec↔plan gate and it repairs and stops only while NO change is open). A change instead flows: analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta (finalize-delta merges the delta into spec.md + domain-model.md, and the change's delta API plan into api-plan.md — not the lane plans, which are derived from those three — but leaves the change open; analyze-slice verifies the slice against the merged master; close-delta archives the change and bumps the version). ⚠️ With more than one change open, plan, analyze-plan-delta and implement ASK which one they are for (pass the id as the argument to skip the prompt) and activate the answer; finalize-delta and close-delta still act on whichever change is active — so finish or close the others deliberately."