aw-spec-cli 0.1.20 → 0.1.22

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

@@ -11,9 +11,18 @@
 # "Slice" is the unit under analysis: the aggregate's code, its paired tests, and
 # its OKF knowledge concept. Three passes over it —
 #   1. BEHAVIOUR   run the tests (paired to the spec's acceptance criteria by the
-#                  design docs); on red, fix up to 3×.
+#                  design docs); on red, fix up to 3×, then stop — the passes below would
+#                  be scoring code already known to be wrong. A slice with NOTHING to run
+#                  (no test project, or a filter that selected zero tests) is a different
+#                  state: no fix attempt can help, so it warns, every other pass runs, and
+#                  the gate fails at the END with what they found.
 #   2. CONFORMANCE check the code against the domain gate overlays AND the bounded
 #                  context's domain-model.md (validate-only).
+#   2b. COMPOSITION is every dependency the slice injects actually BOUND in the service
+#                  lane's composition root? The one failure class the other passes cannot
+#                  see: a container graph is not compile-checked, so an unregistered port
+#                  builds green, passes unit tests that construct their subject directly,
+#                  and fails on the first request. Fixed up to 2×.
 #   3. KNOWLEDGE   refresh + review the slice's OKF concept (advisory).
 # Every fix made here is recorded in that concept, which is also where the slice's
 # file list is READ from (2.3.0 — `aw-xref concept-paths`, replacing the retired
@@ -62,7 +71,7 @@
 
 name: aw-spec-analyze-slice
 description: The design↔code conformance gate — run the slice's tests against its acceptance criteria, check the code against the domain gate overlays AND the bounded context's domain-model.md (every invariant the slice's own aggregate section states must be enforced as written; one another aggregate owns is reported, not blocking), verify the change did not break any referring aggregate (the OKF referrer blast radius) and write a triage report before stopping if it did, refresh + review its OKF concept, and record every fix in it. Sits after finalize-delta on the change path, so the two masters it scores against already carry the change, and before close-delta, so a red gate leaves the change open and recoverable.
-version: 2.4.0
+version: 2.6.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -87,7 +96,33 @@ standards:
 
 vars:
   test_ok: "false"
+  # TWO WAYS PASS 1 IS NOT GREEN, and they are not the same failure. `tests_red` is a suite
+  # that RAN and failed — the fix loop's business, and a stop. `tests_missing` is a slice
+  # with nothing to run (no test project, or a slice filter that selected zero tests):
+  # nothing to repair, so the loop leaves at once, the run carries on through every other
+  # pass, and the gate fails at the end with what they found. See PASS 1.
+  tests_red: "false"
+  tests_missing: "false"
+  tests_present: "true"
+  slice_testable: "true"
+  not_green: "false"
+  test_excerpt: ""
+  test_failing_lanes: ""
+  test_no_setup: "false"
+  test_setup_reason: ""
+  zero_match: "false"
   conformance_ok: "false"
+  # Composition pass (PASS 2b). Defaults to PASSED, because a project with no service lane
+  # has no container to check — the flag is lowered only where a backend lane is declared.
+  wiring_ok: "true"
+  unbound: ""
+  be_declared: "false"
+  be_lane_id: ""
+  be_source_path: ""
+  wiring_notes: ""
+  # The integrity fence blocks through this, not through `integrity_ok` — a fence skipped
+  # because there were no tests to run must not read as a broken referrer.
+  integrity_gate_ok: "true"
   # Invariants the model states under ANOTHER aggregate's section that this slice appears
   # to touch — reported, never blocking, since this slice does not own them. Defaulted so
   # the gate message and the outputs read a real value on a run that skipped the pass.
@@ -101,9 +136,11 @@ vars:
   # Integrity pass (referrer blast radius) defaults — safe values if xref/test-run is
   # skipped or errors, so the gate reads a real verdict rather than an empty var.
   integrity_ok: "false"
-  referrer_csv: ""
+  referrer_csv: ""          # referrers THAT HAVE CODE — what the fence can actually run
   referrer_count: "0"
   referrer_names: ""
+  unbuilt_referrers: ""     # referrers that are planned and not implemented: nothing to run
+  unbuilt_count: "0"
   # Pass-3 (OKF) reporting defaults — the knowledge pass is advisory, so these stay
   # readable in the outputs even when a step is skipped or errors out.
   okf_ok: "unknown"
@@ -128,9 +165,10 @@ workflow:
     script: { ref: actions }
     subcommand: feature-paths
     outputs:
-      - { name: feature,     from: "$.feature" }
-      - { name: feature_dir, from: "$.feature_dir" }
-      - { name: spec_file,   from: "$.spec_file" }
+      - { name: feature,      from: "$.feature" }
+      - { name: feature_dir,  from: "$.feature_dir" }
+      - { name: spec_file,    from: "$.spec_file" }
+      - { name: backend_plan, from: "$.backend_plan" }   # the ports + §4.3 wiring the composition pass reads
 
   - id: require_feature
     action: verify_context
@@ -256,13 +294,55 @@ workflow:
           - { name: test_log,     from: "$.log_tail" }
           - { name: test_matched, from: "$.matched" }
           - { name: test_scoped,  from: "$.scoped" }
+          # The lines that NAME the failure, per failing lane, with the command and exit
+          # code that produced them — what the fix step reads. A positional tail can be
+          # entirely green while the failure sits above it.
+          - { name: test_excerpt, from: "$.failing_excerpt" }
+          - { name: test_failing_lanes, from: "$.failing_lanes" }
+          # "No suite ran, and here is why" — no test script, no runner, no test project.
+          # Distinct from a red suite, and from a scoped filter that matched nothing.
+          - { name: test_no_setup,     from: "$.no_setup" }
+          - { name: test_setup_reason, from: "$.setup_reason" }
       - id: green_break
         action: break
         condition: "{{test_ok}} == true"
+      # WAS A SUITE ACTUALLY RUN? Two ways it was not, and both are STRUCTURAL: there is no
+      # failing test to repair, and three fix attempts against one only spend model passes
+      # to re-discover the same emptiness.
+      #   • `no_setup` — test-run read the runner's own words: no test script wired up, no
+      #     runner installed, no test project. It carries the reason.
+      #   • `matched=false` on a SCOPED run — a .NET slice filter that selected zero tests.
+      #     Only meaningful when scoped, since `matched` reads a .NET-shaped summary line;
+      #     a failing jest run says "Tests: 3 failed" and would otherwise read as empty.
+      # The engine has no compound conditions, so each AND is an ordered assignment —
+      # `not_green` carries "the run was not green" into both tests.
+      - id: flag_not_green
+        action: set
+        vars: { not_green: "true" }
+      - id: flag_no_setup
+        condition: "{{test_no_setup}} == true"
+        action: set
+        vars: { tests_missing: "{{not_green}}" }
+      - id: flag_zero_match
+        condition: "{{test_scoped}} == true"
+        action: set
+        vars: { zero_match: "true" }
+      - id: unflag_zero_match
+        condition: "{{test_matched}} == true"
+        action: set
+        vars: { zero_match: "false" }
+      - id: flag_tests_missing
+        condition: "{{zero_match}} == true"
+        action: set
+        vars: { tests_missing: "{{not_green}}" }
+      - id: missing_break
+        action: break
+        condition: "{{tests_missing}} == true"
       - id: ctx_fix
         action: build_context
         vars:
           test_log: "{{test_log}}"
+          test_excerpt: "{{test_excerpt}}"
         context:
           - { path: "{{spec_file}}" }
           - { path: "{{domain_model}}", optional: true }
@@ -272,29 +352,64 @@ workflow:
         tools: "Read,Write,Edit,Bash"
         permission_mode: acceptEdits
         task: |
-          Tests failed. Make them pass by fixing the code (or a genuinely wrong
+          Tests failed (tool {{test_tool}}, failing lane(s) {{test_failing_lanes}}; each
+          excerpt below is labelled with the lane, its command and its exit code).
+          Make them pass by fixing the code (or a genuinely wrong
           test) in the files in context, keeping behaviour aligned with the spec's
           acceptance criteria (spec in context). Where the spec cites an invariant
           by id (BR-nnn), the bounded context's domain-model.md in context carries
           its text and the entity names it is stated over — read the rule there
-          rather than inferring it from the id. Test log:
+          rather than inferring it from the id.
+          FIX WHAT THE LOG ACTUALLY SAYS. The failing lines are below; if they do not
+          show a real failure, say so and change nothing rather than inventing a repair.
+          Failing lines:
+          {{test_excerpt}}
+          Log tail (context, may be from a lane that passed):
           {{test_log}}
         outputs:
           - { name: fixed_files, from: "$.files" }
 
-  - id: test_gate
+  # THE RED GATE — a suite that RAN and failed, after 3 fix attempts. It stops here, and
+  # deliberately: the passes below score the code against the model, the container and the
+  # referrers, and running them over code whose own tests fail reports findings nobody can
+  # act on until the tests are green. The structural case does NOT come here (see below).
+  - id: flag_tests_red
+    condition: "{{test_ok}} != true"
+    action: set
+    vars: { tests_red: "true" }
+  - id: unflag_tests_red
+    condition: "{{tests_missing}} == true"
+    action: set
+    vars: { tests_red: "false", slice_testable: "false", tests_present: "false" }
+  - id: red_gate
     action: verify_context
-    require_true: test_ok
-    on_false: stop
-    on_false_message: >
+    require_value: tests_red
+    equals: "false"
+    on_mismatch: stop
+    on_mismatch_message: >
       Slice tests not green after 3 fix attempts (tool={{test_tool}}, scoped={{test_scoped}},
-      matched={{test_matched}}). Read those two flags before the log. scoped=true means a
-      per-feature name filter ran, and matched=false then means it selected ZERO tests —
-      the test names do not contain the aggregate name — which the fence treats as a
-      failure, not a vacuous pass. scoped=false means this stack has no per-test selector,
-      so the lane's whole declared suite ran and every failure in it counts here, including
-      ones this feature did not cause; matched is not meaningful in that case. Last log:
-      {{test_log}}
+      matched={{test_matched}}). scoped=true means a per-feature name filter ran; scoped=false
+      means this stack has no per-test selector, so the lane's whole declared suite ran and
+      every failure in it counts here, including ones this feature did not cause.
+      Failing lines (lane(s) {{test_failing_lanes}}):
+      {{test_excerpt}}
+      Last log: {{test_log}}
+
+  # THE STRUCTURAL CASE — nothing to run. It WARNS and carries on, so the passes below
+  # still report what they find; the gate fails at the end, once they have. Before this,
+  # a slice with no tests stopped here and the conformance, composition, integrity and
+  # knowledge passes never executed on any run.
+  - id: warn_no_tests
+    action: verify_context
+    require_true: tests_present
+    on_false: continue
+    on_false_message: >
+      WARNING — this slice has NO TESTS TO RUN (tool={{test_tool}}, scoped={{test_scoped}},
+      matched={{test_matched}}). Reason: {{test_setup_reason}} — or, where that is blank,
+      the slice filter selected zero tests because no test name carries the aggregate's
+      name. Nothing failed and nothing passed. PASS 1 proves nothing on this run, and the integrity fence below
+      is skipped for the same reason — every other pass still runs, and this gate fails at
+      the end with what they found.
 
   # ═══════ PASS 2 — DOMAIN CONFORMANCE: code vs the gate overlay checklist (validation) ═══════
   # With tests green, scan the feature's CODE against the domain gate overlays (the
@@ -402,6 +517,99 @@ workflow:
     on_false: stop
     on_false_message: "Code fails domain conformance after 2 fix attempts (violations: {{conformance_violations}}). Each entry is either a gate-checklist rule or an invariant (BR-nnn) the aggregate's own section of {{domain_model}} states and this code does not enforce as written. Both are constraints plan/implement must satisfy — fix the code, or if the constraint itself is wrong, correct it upstream (/appweaver specify → plan) rather than editing the model to match what was built. Invariants owned by other aggregates in this context were reported, not enforced here: {{model_notes}}"
 
+  # ═══════ PASS 2b — COMPOSITION: is everything the slice injects actually BOUND? ═══════
+  # The one failure class both other passes are blind to. A dependency-injection graph is
+  # not compile-checked, so a port that is injected and never registered builds green, runs
+  # every unit test green (they construct their subject directly), and fails on the first
+  # request that needs it. The mock run shipped exactly that: six of seven handlers took
+  # ports the composition root never bound.
+  #
+  # It reads FILES, so the query declares tools — the composition root is shared
+  # infrastructure and is often not among the slice's own concept paths. Registration by
+  # assembly scan or convention counts; assuming one without finding it does not.
+  - id: lane_resolve
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    outputs:
+      - { name: be_declared,    from: "$.backend_declared" }
+      - { name: be_lane_id,     from: "$.backend_lane_id" }
+      - { name: be_source_path, from: "$.backend_source_path" }
+  - id: wiring_arm
+    condition: "{{be_declared}} == true"
+    action: set
+    vars: { wiring_ok: "false" }
+
+  - id: wiring_loop
+    condition: "{{be_declared}} == true"
+    action: loop
+    while: "{{wiring_ok}} != true"
+    max_iterations: 2
+    steps:
+      - id: ctx_wiring
+        action: build_context
+        context:
+          - { path: "{{backend_plan}}", optional: true }   # §2.1 ports + §4.1 adapters + §4.3 wiring
+        context_from: all_paths
+      - id: check_wiring
+        action: agent_query
+        tools: "Read,Grep"
+        schema: { ok: true, unbound: [ { dependency: "<injected type>", injected_by: "<file:type>", checked: "<the registration file(s) read>" } ], notes: [ "<a binding worth a second look>" ] }
+        mock: { ok: true, unbound: [], notes: [] }
+        task: |
+          WOULD THIS SLICE RUN? Check the service lane's composition against its code.
+          The lane is `{{be_lane_id}}` and its source path is `{{be_source_path}}`; the
+          backend plan is in context, and its §2.1 Ports, §4.1 Persistence and §4.3 Wiring
+          say what has to be bound.
+
+          1. Collect every dependency this slice's own types take by INJECTION — handler,
+             endpoint, adapter and service constructors, and the ports the plan names.
+          2. Read the lane's composition root: wherever this stack registers services (a
+             Program/Startup file, a registration/module/configuration class, a container
+             module, an assembly scan). Open the files; do not infer from names.
+          3. For each dependency, say whether the container binds it — an explicit
+             registration, an assembly scan or convention you have CONFIRMED covers that
+             type, or the framework itself providing it (a logger, a clock, an options
+             object, the HTTP context). A scan you assumed rather than found is not a
+             binding.
+
+          Every dependency with no binding is an `unbound` entry, naming where it is
+          injected and which registration file(s) you read. A binding that exists but whose
+          LIFETIME contradicts what it holds — a singleton capturing a scoped unit of work,
+          a scoped dependency in a singleton — goes in `notes`, which never affects ok.
+          Judge only this slice's types; another feature's unbound port is not this gate's.
+          ok=true only when every dependency this slice injects is bound.
+        outputs:
+          - { name: wiring_ok, from: "$.ok" }
+          - { name: unbound,   from: "$.unbound" }
+          - { name: wiring_notes, from: "$.notes" }
+      - id: wiring_break
+        action: break
+        condition: "{{wiring_ok}} == true"
+      - id: fix_wiring
+        action: agent_generate
+        tools: "Read,Write,Edit,Bash"
+        permission_mode: acceptEdits
+        task: |
+          Bind these dependencies in the `{{be_lane_id}}` lane's composition root, under
+          `{{be_source_path}}`: {{unbound}}
+          Register each one the way this project already registers its neighbours — same
+          file, same helper, same lifetime convention — and bind the implementation the
+          plan's §4.1 / §4.3 names, never a new one you invent. Change no behaviour: this
+          is wiring, not design. If a dependency has NO implementation to bind because
+          nothing was ever written for it, do not stub one — leave it and say so, since
+          that is a generation gap /appweaver implement closes.
+          Then re-run the slice's tests (Bash) to confirm they stay green.
+        outputs:
+          - { name: wiring_fixes, from: "$.files" }
+
+  - id: wiring_gate
+    action: verify_context
+    require_true: wiring_ok
+    on_false: stop
+    on_false_message: "The service lane's container does not bind everything this slice injects, after 2 fix attempts: {{unbound}}. A dependency-injection graph is not compile-checked, so this builds green and fails on the first request that needs it. Bind each one in the lane's composition root under {{be_source_path}} — or, if nothing was ever written to bind, run /appweaver implement to generate it. Lifetime notes (not blocking): {{wiring_notes}}"
+
   # ═══════ INTEGRITY — did this feature's change break any aggregate that USES it? ═══════
   # The slice is green + domain-conformant on its own. But a change to a feature can break
   # any OTHER aggregate that references it. Ask the OKF Cross-References index "who refers to
@@ -411,6 +619,12 @@ workflow:
   # broken referrer STOPS the gate for a human to resolve, it is not auto-fixed here.
   # Empty referrer set (a leaf feature, or the only aggregate in the repo) → the fence is just
   # the feature's own tests again → passes trivially, blocks nothing.
+  #
+  # THE FENCE TAKES THE BUILT HALF OF THE CLOSURE. Edges are read off the lane PLAN, so a
+  # referrer can be fully planned and hold no code: running its tests means running none,
+  # and this fence would report that emptiness as a result. An unbuilt referrer is still
+  # counted and named — it refers to this aggregate and has never been exercised against
+  # it, which is a different statement from passing.
   - id: xref_referrers
     action: execute_script
     on_error: continue
@@ -418,11 +632,18 @@ workflow:
     subcommand: list
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: referrer_csv,   from: "$.referrer_closure_csv" }
-      - { name: referrer_count, from: "$.referrer_closure_count" }
-      - { name: referrer_names, from: "$.referrer_closure" }
+      - { name: referrer_csv,     from: "$.built_closure_csv" }
+      - { name: referrer_count,   from: "$.built_count" }
+      - { name: referrer_names,   from: "$.built_closure" }
+      - { name: unbuilt_referrers, from: "$.unbuilt_closure_csv" }
+      - { name: unbuilt_count,     from: "$.unbuilt_count" }
 
+  # Skipped when PASS 1 found nothing to run: this is the same test command over a wider
+  # scope, so with no tests it would report the same emptiness a second time and fail a
+  # fence over it. `integrity_gate_ok` is what blocks, and it stays true for a fence that
+  # never ran — `integrity_ok` keeps reporting what actually happened.
   - id: run_integrity
+    condition: "{{tests_missing}} == false"
     action: execute_script
     on_error: continue
     script: { ref: actions }
@@ -431,6 +652,12 @@ workflow:
     outputs:
       - { name: integrity_ok,  from: "$.fence_green" }
       - { name: integrity_log, from: "$.log_tail" }
+  # Ordered assignment again: a fence that is not green blocks UNLESS it was skipped, and
+  # `tests_missing` carries exactly that (it reads "true" only when the fence did not run).
+  - id: integrity_verdict
+    condition: "{{integrity_ok}} != true"
+    action: set
+    vars: { integrity_gate_ok: "{{tests_missing}}" }
 
   # On a RED fence, author a durable triage report BEFORE stopping — a broken referrer
   # means someone must go fix ANOTHER slice, so this is a record, not scrollback (mirrors
@@ -450,7 +677,7 @@ workflow:
     context_from: all_paths
   - id: write_broken_referrers
     action: agent_author
-    condition: "{{integrity_ok}} != true"
+    condition: "{{integrity_gate_ok}} == false"
     include_standards: false                       # a triage report, not generated code
     output_target: { type: file, path: "{{feature_dir}}/broken-referrers.md" }
     task: |
@@ -458,7 +685,10 @@ workflow:
       REFER to this feature whose tests went red when this feature's change was run
       against them. This is a triage record for a human — analyze-slice does NOT fix a
       referrer (that is the referrer's own slice's job). Referrer blast radius
-      ({{referrer_count}}): {{referrer_names}}. Failing test log:
+      ({{referrer_count}}): {{referrer_names}}. Also referring to this aggregate but NOT
+      YET BUILT ({{unbuilt_count}}): {{unbuilt_referrers}} — planned, holding no code, so
+      the fence ran nothing for them; say plainly that they were not exercised rather than
+      leaving them out of the report. Failing test log:
       {{integrity_log}}
       Write markdown, in this order:
       - `# Broken Referrers — <feature>` and a one-line statement of what this file is:
@@ -488,7 +718,7 @@ workflow:
 
   - id: integrity_gate
     action: verify_context
-    require_true: integrity_ok
+    require_true: integrity_gate_ok
     on_false: stop
     on_false_message: "Integrity check failed — this feature's change breaks a test in an aggregate that REFERS to it. Referrer blast radius ({{referrer_count}}): {{referrer_names}}. Triage written to {{feature_dir}}/broken-referrers.md — resolve each in the referrer's own slice (or reconsider this feature's contract change), then re-run. Last log: {{integrity_log}}"
 
@@ -545,6 +775,26 @@ workflow:
       - { name: okf_ok,      from: "$.ok" }
       - { name: okf_orphans, from: "$.orphan_count" }
 
+  # THE LAST GATE — a slice with no tests fails HERE, not at PASS 1, so everything the
+  # other passes found has already been reported and any fix they made is on disk. It sits
+  # before the after-hooks, because an extension wired to `after_analyze_slice` runs on a
+  # slice this gate has passed.
+  - id: untested_gate
+    action: verify_context
+    require_true: tests_present
+    on_false: stop
+    on_false_message: >
+      The slice was analysed but NOT tested — it has no tests to run (tool={{test_tool}},
+      scoped={{test_scoped}}, matched={{test_matched}}). Reason: {{test_setup_reason}}.
+      So PASS 1 and the integrity fence proved nothing. Everything above ran: domain
+      conformance={{conformance_ok}}, composition={{wiring_ok}}, OKF index={{okf_ok}}.
+      A lane whose test command is not wired up is fixed in that lane — add the script or
+      the runner its declared command expects, or correct the command in
+      .appweaver/stacks.json. Otherwise, generate the missing tests —
+      /appweaver implement writes a paired test per plan element, under the test path the
+      lane declares — or, if the tests exist, name them so each carries its aggregate's
+      name, which is what the slice filter selects on. Then re-run /appweaver analyze-slice.
+
   - id: resolve_post_hooks
     action: execute_script
     script: { ref: actions }
@@ -570,7 +820,15 @@ outputs:
   # Reported by the conformance pass and never gated — surfaced so a real cross-aggregate
   # leak is visible rather than only living in one query's answer.
   model_notes: "{{model_notes}}"
+  # The composition pass. `true` with no backend lane declared — there is no container.
+  # `wiring_notes` are lifetime observations, reported and never gated.
+  wiring_ok: "{{wiring_ok}}"
+  wiring_notes: "{{wiring_notes}}"
   test_tool: "{{test_tool}}"
+  # false when the slice had no tests to run — PASS 1 and the integrity fence proved
+  # nothing on this run, and the gate failed at the end saying so.
+  tests_present: "{{tests_present}}"
+  tests_matched: "{{test_matched}}"
   referrer_count: "{{referrer_count}}"
   referrer_blast_radius: "{{referrer_names}}"
   okf_concept: "{{okf_concept}}"

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

@@ -80,7 +80,7 @@
 
 name: aw-spec-constitution
 description: Create or update the split project constitution — constitution.technical.md (technology base) + constitution.ui.md (the frontend lane's base, only where a lane exists) + constitution.domain.md (active domain addenda), each version-bumped with a Sync Impact Report, then composed into constitution.md. Project-level, run-once/amend — not a per-feature phase.
-version: 2.4.0
+version: 2.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -561,9 +561,9 @@ workflow:
         invent principles, and do NOT reach for a rule file the map did not supply. If NO
         domain rule file was loaded, say so in the Sync Impact Report and keep the principles
         to what the user input actually supports.
-      - Author ONLY the domain layer: the adopted modelling standard, the domain
-        principles, domain folder additions, regulatory posture & security addenda, and
-        domain governance overrides. For each domain principle, state which technical
+      - Author ONLY the domain layer: the project identity, the adopted modelling
+        standard, the domain principles, domain folder additions, regulatory posture &
+        security addenda, and domain governance overrides. For each domain principle, state which technical
         principle it EXTENDS. Do NOT restate the technical half's principles or the base
         governance — reference them. Where constitution.technical.md is absent from
         context the project declared no service lane and there is no technical half to