aw-spec-cli 0.1.21 → 0.1.23

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}}"]
@@ -671,4 +771,7 @@ outputs:
   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."
-  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."
+  # 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."

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

@@ -0,0 +1,159 @@
+# =============================================================================
+# 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" }   # kebab-case route segment
+      - { name: spec_file,      from: "$.spec_file" }
+      - { name: spec_exists,    from: "$.spec_exists" }
+
+  # domain and prototype_root have their OWN resolvers — feature-paths answers for the
+  # feature's documents and nothing else, so binding them here left both empty and the
+  # emptiness reached the prompts as a blank path segment rather than an error.
+  - id: resolve_domain
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: resolve-domain
+    args: ["--command", "/aw-spec-ui-model"]
+    outputs:
+      - { name: domain, from: "$.domain" }
+
+  - id: resolve_prototype_lane
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { 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."