aw-spec-cli 0.1.20 → 0.1.22

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

@@ -137,7 +137,7 @@
 
 name: aw-spec-onboard
 description: Onboard an existing codebase for brownfield DEVELOPMENT — a deterministic whole-repo scan produces a high-level OKF feature map (folders/concepts) PLUS the project-level governance scaffold (split constitution + guardrails/projects/brf-<domain>/ with its DOMAIN rule files at domain/ + domain-rule-bindings + code-derived TECHNICAL rule files at service/ + tech-rule-bindings + activated domain), all provisional-from-scan and refined per slice by adopt. Where the scan finds a frontend lane in the CODE, it also authors that lane's half — constitution.ui.md (UX-*) — and its code-derived rule files at brf-<domain>/frontend/, mapped under `## /aw-spec-ui-constitution`; a backend-only repo gets none of it. Every rule tier is reverse-engineered from the CODE alone (never a greenfield rule file), evidenced-only, and WIRED per-workflow so the whole forward pipeline AND adopt govern against THIS codebase — never a greenfield fallback. It also reverse-engineers the repo's own technical structure into a project-specific design + delta-design template pair, installed as the project template overrides, and — where the lane exists — the frontend lane's own pair from the UI source. Every authoring step is shaped by a NEUTRAL rev-templates skeleton; no greenfield constitution, rule file or document template is ever placed in context. Accepts an optional concerns list to look for (onboard decides which are actually present). Reads any declared lane, never writes one. No migration content; never modifies source.
-version: 2.0.0
+version: 2.1.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -1270,8 +1270,8 @@ workflow:
         numeral is whatever the code supported — never a value carried over from another
         constitution. If it mandates no modelling methodology, say so plainly rather than
         supplying one.
-      - Author ONLY the domain layer: domain principles, domain folder additions,
-        regulatory/security posture, domain governance — from the project + charter. NUMBER
+      - Author ONLY the domain layer: project identity, domain principles, domain folder
+        additions, regulatory/security posture, domain governance — from the project + charter. NUMBER
         them by CONTINUING the technical half's roman numerals: READ
         constitution.technical.md (in context), find its LAST numeral N, start the first
         domain principle at N+1 (do NOT assume it ends at XV). TITLE each by DOMAIN

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

@@ -154,6 +154,10 @@ vars:
   # answer; master_exists is what makes the menu appear at all.
   master_exists: "false"       # a DECLARED lane's master plan was already on disk
   plan_target: "main"          # main | delta — the answer to the one question this phase asks
+  # The OKF edges this run publishes from the master service plan (main path only).
+  record_master_edges: "false"
+  xref_edge_count: "0"
+  xref_stubbed: "[]"           # used siblings that had no concept yet and were stubbed
   plan_choice: ""              # the raw selection (a label): the MAIN row, a change, or the NEW row
   main_label: ""               # cr-list --include-main's exact label, to test the selection against
   new_label: ""                # cr-list --include-new's
@@ -1069,6 +1073,41 @@ workflow:
     action: include
     module: .appweaver/orchestrator/modules/delta-plan.orch.yaml
 
+  # 6b. CROSS-SLICE EDGES, from the document that states them. `aw-xref record` reads the
+  #     MASTER service plan — §1 References-by-id and the External integrations table — and
+  #     writes a Cross-References row into every sibling aggregate this one uses. Its input
+  #     is the plan and nothing else, yet it used to run only at implement: until a feature
+  #     was BUILT it contributed no edges, so `xref list` answered "0 downstream users" for
+  #     an aggregate a planned feature already depended on, and `xref tree` sorted the two
+  #     into the same wave. The information was in this document the whole time.
+  #
+  #     MAIN PATH ONLY. On the delta path the master plan still holds the PRE-change
+  #     dependencies, so recording here would publish stale references; finalize-delta
+  #     records them after the change merges, which is the same reason implement skips it.
+  #     Reconcile-on-write, so re-recording at implement is idempotent and a dependency
+  #     dropped by a later re-derivation self-heals. Best-effort: never fails the authoring.
+  - id: record_edges_clear
+    action: set
+    vars: { record_master_edges: "false" }
+  - id: record_edges_main
+    condition: "{{plan_target}} == main"
+    action: set
+    vars: { record_master_edges: "true" }
+  - id: record_edges_no_lane
+    condition: "{{be_mode}} == skip"
+    action: set
+    vars: { record_master_edges: "false" }
+  - id: xref_record
+    condition: "{{record_master_edges}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: record
+    args: ["--feature-dir", "{{feature_dir}}", "--design", "{{backend_plan}}", "--origin", "auto"]
+    outputs:
+      - { name: xref_edge_count, from: "$.edge_count" }
+      - { name: xref_stubbed,    from: "$.stubbed" }
+
   # ═══════════ HANDOFF — authoring only; the gates are SEPARATE stages ═══════
   #   • MAIN (bootstrap or re-derivation) → /appweaver analyze-plan (spec↔plan
   #     conformance gate) → implement. No change is opened either way.

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

@@ -95,10 +95,14 @@ vars:
   has_dependants: "false"
   dependant_ids: ""
   dependant_count: "0"
-  # The two refusal flags, both DOWN by default and raised only by the good state — see
+  wave_problem: ""            # which changes could not be ordered, and why that ends the check
+  unordered_ids: ""
+  unordered_count: "0"
+  # The three refusal flags, all DOWN by default and raised only by the good state — see
   # the gates below for why fail-closed is the right default here.
   not_merged: "false"
   no_dependants: "false"
+  wave_ordering_ok: "false"
   recall_confirmed: "false"
   recalled: "false"
   archived_dir: ""
@@ -170,7 +174,7 @@ workflow:
       - { name: delta_model,      from: "$.delta_model" }
       - { name: wave,             from: "$.wave" }
 
-  # 4. THE TWO REFUSALS, both answered from disk in one call — see the header for why each
+  # 4. THE THREE REFUSALS, all answered from disk in one call — see the header for why each
   #    one is a stop rather than a warning.
   - id: recall_check
     action: execute_script
@@ -178,11 +182,16 @@ workflow:
     subcommand: cr-recall-check
     args: ["--cr-id", "{{cr_choice}}", "--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: merged,          from: "$.merged" }
-      - { name: merge_evidence,  from: "$.merge_evidence" }
-      - { name: has_dependants,  from: "$.has_dependants" }
-      - { name: dependant_ids,   from: "$.dependant_ids" }
-      - { name: dependant_count, from: "$.dependant_count" }
+      - { name: merged,           from: "$.merged" }
+      - { name: merge_evidence,   from: "$.merge_evidence" }
+      - { name: has_dependants,   from: "$.has_dependants" }
+      - { name: dependant_ids,    from: "$.dependant_ids" }
+      - { name: dependant_count,  from: "$.dependant_count" }
+      - { name: wave,             from: "$.wave" }
+      - { name: wave_ordering_ok, from: "$.wave_ordering_ok" }
+      - { name: wave_problem,     from: "$.wave_problem" }
+      - { name: unordered_ids,    from: "$.unordered_ids" }
+      - { name: unordered_count,  from: "$.unordered_count" }
 
   # Each refusal is a RAISE then a gate, not a conditional gate: the raise fires only on
   # the good state, so a value that never arrived (the script errored, the field was
@@ -199,6 +208,18 @@ workflow:
     on_false: stop
     on_false_message: "Change {{cr_id}} has already been MERGED — /appweaver finalize-delta folded it into spec.md and the context's domain-model.md, and the spec's Change History carries it: {{merge_evidence}}. The masters now describe behaviour that includes this change, so withdrawing it would leave them describing work no open change accounts for. A recall cannot un-merge, and this stage will not pretend otherwise. If the change should not have landed, finish it (/appweaver analyze-slice → close-delta) and then open a NEW change that reverses it with /appweaver specify — that keeps both the landing and the reversal in the ledger, which is what a reader of the spec needs to see."
 
+  # WAVE ORDERING IS A PRECONDITION OF THE FENCE BELOW, not a finding of it. The dependant
+  # test is `their wave > mine`, and a wave that cannot be read used to answer that as 1, so
+  # an unstamped change failed the test and was not counted — recall then withdrew the
+  # ground from under a change it could not see, which is the failure this stage exists to
+  # prevent. Waves have no ceiling, so unlike the merge fence there is no floor that makes
+  # an unordered neighbour harmless: every one of them holds recall until it is stamped.
+  - id: require_wave_ordering
+    action: verify_context
+    require_true: wave_ordering_ok
+    on_false: stop
+    on_false_message: "Recall REFUSED — the wave fence cannot order change {{cr_id}}, so it cannot tell you what was built on top of it: {{wave_problem}}. Withdrawing a change that something else was planned against is exactly what this stage refuses to do blind. A wave is stamped by a script; `**Wave**: [N]` is the unfilled template line, which means the stamp never ran on that document. Stamp each one — `.appweaver/scripts/bash/aw-spec-actions.sh cr-wave-derive --cr-id <CR-id> --stamp` derives the wave from that change's own `## Depends on` section and writes it — then re-run /appweaver recall-delta {{cr_id}}."
+
   - id: no_dependants_raise
     condition: "{{has_dependants}} == false"
     action: set

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

@@ -14,8 +14,13 @@
 # evidence sits in, and both are only ever proposals — an operator selects from the
 # list or types a path the kit has never seen.
 #
-#   stack-list --suggest backend  → select stack → ask source path → lane-declare
-#   stack-list --suggest frontend → select stack → ask source path → lane-declare
+#   stack-list --suggest backend  → select stack → stack-list --profile → ask source path → lane-declare
+#   stack-list --suggest frontend → select stack → stack-list --profile → ask source path → lane-declare
+#
+# THE SOURCE-PATH OPTIONS ARE BUILT AFTER THE STACK IS CHOSEN. Most profiles of a kind
+# share a default root (six frontend stacks default to web/), so a list built before the
+# choice cannot say which stack an option belongs to. The second stack-list call answers
+# for the chosen stack alone.
 #
 # (none) IS A REAL ANSWER FOR EITHER LANE, and it is how a project says "I do not
 # have one of these". A backend-only project answers (none) to the UI lane; a
@@ -56,7 +61,7 @@
 
 name: aw-spec-select-stack
 description: Declare the project's lanes — each lane's STACK and its SOURCE PATH — 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.0.0
+version: 2.3.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -93,9 +98,7 @@ workflow:
       - { name: api_options,       from: "$.select_options" }
       - { name: api_ids,           from: "$.ids" }
       - { name: api_preselect,     from: "$.preselect" }
-      - { name: api_root_options,  from: "$.root_options" }
-      - { name: api_detected,      from: "$.detected_profile" }
-      - { name: api_detected_root, from: "$.detected_root" }
+      - { name: api_detected,      from: "$.detected_summary" }
       - { name: api_none_sentinel, from: "$.none_sentinel" }
 
   # 2. No profiles installed is a setup error, not an empty menu. Gated on the
@@ -114,7 +117,7 @@ workflow:
   #    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}} (leading 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:"
     options_from_variable: api_options
     preselect_from: api_preselect
     single_option_confirm: true
@@ -133,14 +136,24 @@ workflow:
     condition: "{{chosen_api}} == {{api_none_sentinel}}"
     vars: { api_selected: "" }
 
-  # 5. WHERE the service lane's source lives. Offered best-first — where the
-  #    evidence actually sits, then each profile's own default — and free text is
-  #    accepted, because a repo that matches no profile still has a source path.
-  #    The label after the path says why it is offered and is stripped on the way in.
+  # 5. WHERE the service lane's source lives. Offered best-first for the CHOSEN stack —
+  #    where its evidence sits, then its own default, then where another stack's
+  #    evidence sits — and free text is accepted, because a repo that matches no
+  #    profile still has a source path. The label after the path says why it is
+  #    offered and is stripped on the way in.
+  - id: list_api_roots
+    action: execute_script
+    condition: "{{api_selected}}"
+    script: { ref: actions }
+    subcommand: stack-list
+    args: ["--kind", "backend", "--suggest", "--profile", "{{chosen_api}}"]
+    outputs:
+      - { name: api_root_options, from: "$.root_options" }
+
   - id: ask_api_source_path
     action: ask
     condition: "{{api_selected}}"
-    prompt: "Service lane SOURCE PATH — the subtree this lane owns, the only place implement may write, and the directory build/test/run act on. Pick one or type your own:"
+    prompt: "Service lane SOURCE PATH — the subtree this lane owns, where implement writes its code, and the directory build/test/run act on. Its tests go to the stack's test path beside it (tests/ next to src/ for .NET), shown in the summary. Pick one or type your own:"
     options_from_variable: api_root_options
     answer_var: api_source_path
 
@@ -159,6 +172,7 @@ workflow:
       - { name: api_lane_id,     from: "$.lane_id" }
       - { name: api_profile,     from: "$.profile" }
       - { name: api_root,        from: "$.source_path" }
+      - { name: api_test_path,   from: "$.test_path" }
       - { name: api_root_exists, from: "$.root_exists" }
 
   # ═══════════════ UI LANE ════════════════════════════════════════════════════
@@ -176,15 +190,13 @@ workflow:
       - { name: ui_options,       from: "$.select_options" }
       - { name: ui_ids,           from: "$.ids" }
       - { name: ui_preselect,     from: "$.preselect" }
-      - { name: ui_root_options,  from: "$.root_options" }
-      - { name: ui_detected,      from: "$.detected_profile" }
-      - { name: ui_detected_root, from: "$.detected_root" }
+      - { name: ui_detected,      from: "$.detected_summary" }
       - { name: ui_none_sentinel, from: "$.none_sentinel" }
 
   # 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}} (leading 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:"
     options_from_variable: ui_options
     preselect_from: ui_preselect
     single_option_confirm: true
@@ -199,7 +211,16 @@ workflow:
     condition: "{{chosen_ui}} == {{ui_none_sentinel}}"
     vars: { ui_selected: "" }
 
-  # 9. WHERE the UI lane's source lives.
+  # 9. WHERE the UI lane's source lives, offered for the chosen UI stack.
+  - id: list_ui_roots
+    action: execute_script
+    condition: "{{ui_selected}}"
+    script: { ref: actions }
+    subcommand: stack-list
+    args: ["--kind", "frontend", "--suggest", "--profile", "{{chosen_ui}}"]
+    outputs:
+      - { name: ui_root_options, from: "$.root_options" }
+
   - id: ask_ui_source_path
     action: ask
     condition: "{{ui_selected}}"
@@ -217,6 +238,7 @@ workflow:
       - { name: ui_lane_id,     from: "$.lane_id" }
       - { name: ui_profile,     from: "$.profile" }
       - { name: ui_root,        from: "$.source_path" }
+      - { name: ui_test_path,   from: "$.test_path" }
       - { name: ui_root_exists, from: "$.root_exists" }
 
   # ═══════════════ CHECK + REPORT ═════════════════════════════════════════════
@@ -257,7 +279,7 @@ workflow:
   - id: api_summary_lane
     action: set
     condition: "{{api_declared}}"
-    vars: { api_summary: "{{api_lane_id}} ({{api_profile}}) at {{api_root}} — source path exists: {{api_root_exists}}" }
+    vars: { api_summary: "{{api_lane_id}} ({{api_profile}}) at {{api_root}}, tests at {{api_test_path}} — source path exists: {{api_root_exists}}" }
 
   - id: ui_summary_none
     action: set
@@ -265,7 +287,7 @@ workflow:
   - id: ui_summary_lane
     action: set
     condition: "{{ui_declared}}"
-    vars: { ui_summary: "{{ui_lane_id}} ({{ui_profile}}) at {{ui_root}} — source path exists: {{ui_root_exists}}" }
+    vars: { ui_summary: "{{ui_lane_id}} ({{ui_profile}}) at {{ui_root}}, tests at {{ui_test_path}} — source path exists: {{ui_root_exists}}" }
 
   # 12. Read the finished declaration back through the reader every later workflow
   #     uses, so what this run reports is what they will resolve.
@@ -287,10 +309,12 @@ outputs:
   ui_lane: "{{ui_summary}}"
   api_source_path: "{{api_root}}"
   ui_source_path: "{{ui_root}}"
+  api_test_path: "{{api_test_path}}"
+  ui_test_path: "{{ui_test_path}}"
   api_source_path_exists: "{{be_root_exists}}"
   ui_source_path_exists: "{{fe_root_exists}}"
-  api_detected: "{{api_detected}} at {{api_detected_root}}"
-  ui_detected: "{{ui_detected}} at {{ui_detected_root}}"
+  api_detected: "{{api_detected}}"
+  ui_detected: "{{ui_detected}}"
   prototype: "{{prototype}}"
-  note: "Lanes persisted to .appweaver/stacks.json. Each lane carries a STACK and a SOURCE PATH, and both are load-bearing. The SOURCE PATH is ownership: implement's service lane writes 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 — overlapping paths 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 — empty on a greenfield repo with nothing to detect. A source path 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 source path, or drop a lane with (none); it is the only workflow that may write this file."
-  next: "GREENFIELD: /appweaver select-domain → constitution → select-feature → specify. BROWNFIELD: /appweaver onboard — it reverse-engineers out of the source paths declared here and generates the project (no select-domain; onboard derives and activates it from the code). Run this workflow FIRST in either sequence: constitution reads the declaration to decide which halves to author, and onboard reads it to decide what to scan."
+  note: "Lanes persisted to .appweaver/stacks.json. Each lane carries a STACK and a SOURCE PATH, and both are load-bearing. The SOURCE PATH 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 source path 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 source path 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 source path, or drop a lane with (none); it is the only workflow that may write this file."
+  next: "GREENFIELD: /appweaver foundation — once per lane, to scaffold a compiling project into each source path declared here (skip it for a lane whose code already exists, or scaffold with the stack's own tooling) — then /appweaver select-domain → constitution → select-feature → specify. BROWNFIELD: /appweaver onboard — it reverse-engineers out of the source paths declared here and generates the project (no select-domain; onboard derives and activates it from the code). Run this workflow FIRST in either sequence: foundation unpacks into the source paths declared here, constitution reads the declaration to decide which halves to author, and onboard reads it to decide what to scan."

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

@@ -107,6 +107,14 @@ standards:
 
 vars:
   spec_all_pass: "false"     # validation-loop guard, flipped by the validate query
+  nn_count: "0"              # ratified NON-NEGOTIABLE principles, from principles-list.
+                             # 0 = a project that ratified none, which skips the gate.
+  nn_titles: ""              # those principles, for the judge's prompt
+  nn_compliant: "false"      # per-clarification verdict. DEFAULTS TO REFUSE: the gate
+                             # reads it, so a judge that never answered stops the run
+                             # rather than passing an unexamined answer through.
+  nn_principle: ""           # the principle a departing answer was judged against
+  nn_why: ""                 # what it requires and what the answer does instead
   checklist_total: "0"       # bound by checklist-read
   checklist_passed: "0"      # stays 0 when the checklist has no items to score
   cr_id: ""                  # set on the DELTA path only
@@ -520,6 +528,23 @@ workflow:
 
   # 6. Resolve [NEEDS CLARIFICATION] markers interactively (≤3). Non-interactive
   #    runs answer with the first/recommended option (a documented default).
+  #
+  #    THE DEFAULT IS WHY THIS IS GOVERNED. A non-interactive run answers with options[0],
+  #    so whatever the extraction listed first becomes project policy unattended — and a
+  #    clarification is asked at exactly the altitude where a ratified principle already
+  #    has an answer. The constitution halves ARE in context here (build_context put them
+  #    in the envelope, which include_standards: false does not touch), but nothing told
+  #    the extraction that a principle outranks a question, and nothing checked the answer
+  #    afterwards. Both halves of that are below: the ordering rule in the task, and the
+  #    per-answer gate inside the loop.
+  - id: nn_principles
+    action: execute_script
+    script: { ref: actions }
+    subcommand: principles-list
+    outputs:
+      - { name: nn_count,  from: "$.count" }
+      - { name: nn_titles, from: "$.titles_csv" }
+
   - id: extract_clarifications
     action: agent_query
     context: ["{{quality_target}}"]
@@ -528,6 +553,15 @@ workflow:
       Extract up to 3 unresolved "[NEEDS CLARIFICATION: <question>]" markers from
       the document in context (a feature spec, or one change's delta-spec), most
       scope/security/UX-impacting first. Return {"clarifications":[]} if there are none.
+
+      A RATIFIED PRINCIPLE IS NOT A QUESTION. The constitution halves in context carry
+      principles marked (NON-NEGOTIABLE). Where one of them already settles a marker,
+      it is not a clarification: DROP it from the list — the answer is the principle,
+      and the document is corrected to match it in the quality loop. Offering it as a
+      choice invites a project to vote on something already ratified.
+      For a marker that merely TOUCHES such a principle, every option you list must be
+      compatible with it, and the most compliant option must be FIRST — an unattended
+      run takes the first one.
     schema: { clarifications: [ { id: c1, question: "<the question>", options: ["<answer A>", "<answer B>", "<answer C>"] } ] }
     mock: { clarifications: [] }
     outputs:
@@ -545,6 +579,72 @@ workflow:
         options_from: "{{c.options}}"
         answer_key: "{{c.id}}"
         answer_var: c_answer
+
+      # THE ANSWER IS CHECKED BEFORE IT IS WRITTEN IN. Placed between the ask and the
+      # rewrite on purpose: once resolve_clar has folded the answer into a requirement it
+      # is ordinary spec prose, and catching it then means unpicking a document rather
+      # than declining an answer. Judged one answer at a time so the stop can quote the
+      # question that caused it.
+      #
+      # The agent judges ONLY against the principles nn_principles found — a citation
+      # outside that list is visibly wrong, which is the point of enumerating them with a
+      # script instead of asking one agent to both find the principle and object to it.
+      #
+      # ASKED IN THE POSITIVE, AND RESET FIRST. The gate below reads nn_compliant, so an
+      # answer the judge never delivered — a malformed reply, a step that did not run —
+      # leaves "false" standing and STOPS. Asking "does it contradict?" would invert that:
+      # the same silence would read as no contradiction found. The reset is what makes it
+      # per-iteration; vars outlive a loop pass, so without it the second clarification
+      # would inherit the first one's verdict.
+      - id: governance_reset
+        action: set
+        vars:
+          nn_compliant: "false"
+          nn_principle: ""
+          nn_why: ""
+
+      # Skipped where a project ratified no NON-NEGOTIABLE principle: with nothing to
+      # depart from there is nothing to ask, and the gate is skipped on the same
+      # condition rather than reading the "false" this reset just wrote.
+      - id: governance_check
+        condition: "{{nn_count}} != 0"
+        action: agent_query
+        context: ["{{quality_target}}"]
+        include_standards: false
+        task: |
+          The constitution halves in context ratify these NON-NEGOTIABLE principles:
+            {{nn_titles}}
+          A question was raised about this specification and has just been answered:
+            Question: {{c.question}}
+            Answer:   {{c_answer}}
+          Is that answer COMPLIANT with those principles — that is, can the specification
+          be amended to say it without asserting something a principle forbids or omitting
+          something a principle requires?
+          Judge only against the principles listed above, and when it is not compliant
+          cite the one it departs from by its id. A principle the question does not engage
+          is not a departure, and neither is an answer a principle simply does not speak
+          to; where none is engaged the answer is compliant. Report a departure only where
+          you can state what the principle requires and what the answer does instead.
+        schema: { compliant: true, principle: "<id, or empty>", why: "<one sentence, or empty>" }
+        mock: { compliant: true, principle: "", why: "" }
+        outputs:
+          - { name: nn_compliant,  from: "$.compliant" }
+          - { name: nn_principle,  from: "$.principle" }
+          - { name: nn_why,        from: "$.why" }
+
+      # FAIL CLOSED. The constitution's own Governance says a deviation with no named
+      # approver is a defect, not a decision — and this answer has no approver at all: it
+      # was settled in the run, by an operator picking from a menu or by a non-interactive
+      # default. Recording it and carrying on is how an unapproved departure from a
+      # NON-NEGOTIABLE principle reaches code, so the run stops here and the choice goes
+      # back to a human who can either comply or amend the constitution properly.
+      - id: governance_gate
+        condition: "{{nn_count}} != 0"
+        action: verify_context
+        require_true: nn_compliant
+        on_false: stop
+        on_false_message: "The answer to \"{{c.question}}\" departs from NON-NEGOTIABLE principle {{nn_principle}}: {{nn_why}}. That principle is ratified in .appweaver/memory/ and this answer has no approver — it was settled in this run, not by a domain owner, and the constitution's Governance section holds that a deviation with no named approver is a defect rather than a decision. Re-run specify and answer in a way the principle allows; if the project genuinely intends to depart from it, amend the constitution through its own amendment process FIRST (which names the approver the departure needs) and re-run. Nothing was written to {{quality_target}} for this clarification."
+
       - id: resolve_clar
         action: agent_author
         context: ["{{quality_target}}"]
@@ -670,5 +770,5 @@ outputs:
   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; `cr-wave --cr-id {{cr_id}} --wave <n>` moves 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. {{open_count}} change(s) are open on this feature."
   next: "/appweaver plan — BOOTSTRAP authors backend-plan.md from the spec + the domain model; a DELTA (this run opened change {{cr_id}}, wave {{wave}}) authors the delta plans for it. A change then 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."

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

@@ -0,0 +1,141 @@
+# =============================================================================
+# aw-spec-ui-model (orchestrator) — Derive UI Model from Workflow Model
+#
+# Stage 3 of the 4-Stage Spec-Driven UI Generation Pipeline.
+# Consumes `specs/<Feature>/ui/workflow-model.md` and maps workflows into concrete UI surfaces
+# (Pages, Sub-Pages, Drawers, Modals, Dialogs), interaction states (Loading, Empty, Populated, Filtered, Error, Success),
+# user actions, and surface transitions.
+# Writes output artifact to `specs/<Feature>/ui/ui-model.md`.
+#
+# Launch:
+#   /appweaver ui-model [strategy] [guidance]
+# =============================================================================
+
+name: aw-spec-ui-model
+description: Derive the UI Model (specs/<Feature>/ui/ui-model.md) from workflow-model.md, specifying UI surfaces (pages, dialogs, drawers, modals), routes, interaction states, actions, and navigation transitions.
+version: 1.0.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional UI layout or surface guidance.
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+vars:
+  feature: ""
+  feature_dir: ""
+  feature_slug: ""
+  spec_file: ""
+  spec_exists: "false"
+  workflow_model_file: ""
+  workflow_model_exists: "false"
+  active_change: ""
+  has_change: "false"
+  domain: ""
+  prototype_root: ""
+
+workflow:
+
+  # 1. Resolve active feature and paths
+  - id: feature_paths
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: feature-paths
+    outputs:
+      - { name: feature,        from: "$.feature" }
+      - { name: feature_dir,    from: "$.feature_dir" }
+      - { name: feature_slug,   from: "$.feature_slug" }
+      - { name: spec_file,      from: "$.spec_file" }
+      - { name: spec_exists,    from: "$.spec_exists" }
+      - { name: domain,         from: "$.domain" }
+      - { name: prototype_root, from: "$.prototype_root" }
+
+  - id: require_feature
+    action: verify_context
+    require_non_empty: feature_dir
+    on_empty: stop
+    on_empty_message: "No active feature selected. Run /appweaver select-feature first."
+
+  - id: require_spec
+    action: verify_context
+    require_true: spec_exists
+    on_false: stop
+    on_false_message: "No specification found for this feature. Run /appweaver specify first."
+
+  # 2. Check workflow-model.md existence
+  - id: check_workflow_model
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: path-exists
+    args: ["--path", "{{feature_dir}}/ui/workflow-model.md"]
+    outputs:
+      - { name: workflow_model_exists, from: "$.exists" }
+
+  - id: require_workflow_model
+    action: verify_context
+    require_true: workflow_model_exists
+    on_false: stop
+    on_false_message: "No Workflow Model found at specs/{{feature}}/ui/workflow-model.md. Run /appweaver workflow-model first."
+
+  # 3. Assemble workflow model & template context
+  - id: ctx_ui_model
+    action: build_context
+    vars:
+      feature_name: "{{feature}}"
+      feature_dir: "{{feature_dir}}"
+      user_preferences: "{{USER_INPUT}}"
+    context:
+      - "{{feature_dir}}/ui/workflow-model.md"
+      - "{{spec_file}}"
+      - { path: ".appweaver/templates/ui-model-template.md", optional: true }
+      - { path: ".appweaver/memory/constitution.ui.md", optional: true }
+
+  # 4. Generate UI Model Artifact (specs/<Feature>/ui/ui-model.md)
+  - id: generate_ui_model
+    action: agent_generate
+    tools: "Read,Write,Edit,Bash"
+    permission_mode: acceptEdits
+    task: |
+      You are authoring Stage 3 (UI Model) of the 4-Stage Spec-Driven UI Pipeline for feature `{{feature_name}}`.
+
+      Target Artifact Path: `{{feature_dir}}/ui/ui-model.md`
+
+      Instructions:
+      1. Read `specs/{{feature}}/ui/workflow-model.md` and `spec.md` in context.
+      2. Translate EVERY workflow (WF-1, WF-2, ...) into explicit **UI Surfaces**:
+         - Determine the appropriate UI surface type for each workflow step: `Page`, `Sub-Page`, `Dialog`, `Drawer`, `Modal`, `View`.
+         - Map routes or component mount paths (e.g. `/{{feature_slug}}`, `/{{feature_slug}}/create`, modal dialog triggers).
+         - Define supported interaction states per surface (`Loading`, `Empty`, `Populated`, `Filtered / Searched`, `Validation Error`, `Submitting`, `Success`, `Error`).
+         - Specify interactive controls, form fields, action buttons, and table/card layouts.
+         - Map explicit navigation & transition triggers (`On Action -> Opens Surface X`).
+      3. Remember the core rule: **Workflow != Single Screen**. A workflow can span multiple surfaces or reuse surfaces with state changes.
+      4. Format output according to `.appweaver/templates/ui-model-template.md`.
+      5. Write the authored markdown content to `{{feature_dir}}/ui/ui-model.md`.
+
+      User Guidance:
+      {{user_preferences}}
+
+      End your final reply with a summary and a ```json fence:
+      ```json
+      {
+        "status": "ok",
+        "feature": "{{feature_name}}",
+        "ui_model_path": "{{feature_dir}}/ui/ui-model.md"
+      }
+      ```
+    outputs:
+      - { name: result, from: "$" }
+
+outputs:
+  feature: "{{feature}}"
+  ui_model_path: "{{feature_dir}}/ui/ui-model.md"
+  next: "Run /appweaver ui-prototype to generate the executable Next.js prototype application."