aw-spec-cli 0.1.21 → 0.1.22

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

@@ -60,7 +60,7 @@
 #      risk of "fixing" the change's new tests back toward pre-change behaviour.
 #   2. A red analyze-slice still lands on an OPEN change, so the remedy is "fix and
 #      re-run" rather than a NEW change to repair the one already shipped.
-# The downstream fence below still guards the MERGE (a change that breaks a dependent
+# The regression fence below still guards the MERGE (a change that breaks a dependent or a co-owner
 # must not reach the master docs); close-delta guards nothing — it is the bookkeeping.
 #
 # Prereqs: run /appweaver implement (answering it with THIS change), then build, then
@@ -89,7 +89,7 @@
 # is one close-delta could never archive, so it must not reach the masters.
 #
 # THE MERGE FENCE — THREE REFUSALS, read off disk in one cr-merge-check call and placed
-# before the downstream fence, because they are free while that one runs a test suite:
+# before the regression fence, because they are free while that one runs a test suite:
 #
 #   REBASE. The delta carries the master version it was authored against (`**Base version**:`,
 #   stamped by cr-setup). If the master has moved, the delta's MODIFIED items name a BEFORE
@@ -137,8 +137,8 @@
 # =============================================================================
 
 name: aw-spec-finalize-delta
-description: Merge ONE chosen open change's delta-spec into the feature's spec.md and its model delta into the bounded context's domain-model.md — one aggregate section at a time, only the aggregates the delta names — in a single transaction, and append the spec's Change History row. ASKS which change (a bare CR id as the argument skips the prompt) and activates it, rather than taking whichever was last opened. Fenced by three hard refusals read off disk before anything is written — a moved base_version (rebase first), another change merged but not yet closed, and an open LOWER-wave predecessor — then by a SCOPED downstream fence over the transitive blast radius (fence_green), which writes a triage report and asks Abort/Override on red. Snapshots both masters to changes/<id>/pre-merge/ immediately before the rewrite. The lane plans are NOT merged — backend-plan.md and frontend-plan.md are derived from these two documents and are re-derived by /appweaver plan main. Leaves the change OPEN — analyze-slice runs next against the merged masters, and close-delta archives the change and bumps the version.
-version: 2.4.0
+description: Merge ONE chosen open change's delta-spec into the feature's spec.md and its model delta into the bounded context's domain-model.md — one aggregate section at a time, only the aggregates the delta names — in a single transaction, and append the spec's Change History row. ASKS which change (a bare CR id as the argument skips the prompt) and activates it, rather than taking whichever was last opened. Fenced by three hard refusals read off disk before anything is written — a moved base_version (rebase first), another change merged but not yet closed, and an open LOWER-wave predecessor — then by a SCOPED regression fence over the whole blast radius (fence_green) — the transitive REFERRER closure and the features that CO-OWN the aggregates this delta touches, which hold no edge to it but whose code is in the same files — writing a triage report and asking Abort/Override on red. Snapshots both masters to changes/<id>/pre-merge/ immediately before the rewrite. The lane plans are NOT merged — backend-plan.md and frontend-plan.md are derived from these two documents and are re-derived by /appweaver plan main. Leaves the change OPEN — analyze-slice runs next against the merged masters, and close-delta archives the change and bumps the version.
+version: 2.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -165,8 +165,16 @@ vars:
   has_changes: "false"  # from cr-list — the DIRECTORY's answer to "is anything open", not the ledger's
   version: ""           # the CURRENT version — unchanged by this stage
   next_version: ""      # what close-delta will bump to; the number the Change History rows carry
-  downstream_count: "0"    # transitive + placeholder-filtered dependents (blast radius); drives the gate
+  downstream_count: "0"    # transitive + placeholder-filtered dependents THAT HAVE CODE; drives the gate
   downstream_csv: ""       # the blast-radius names, fed to the scoped fence's --also and shown to the human
+  unbuilt_count: "0"       # dependants that are planned and not implemented: real, with nothing to re-test
+  unbuilt_csv: ""
+  reached_count: "0"       # the whole closure — what this change reaches, built or not
+  co_owner_count: "0"      # features that CO-OWN the aggregates this delta touches
+  co_owner_csv: ""         # their names, fed to the same fence as a second --also
+  co_owner_aggs: ""        # the aggregates the co-owner search was scoped to
+  co_owner_source: ""      # `delta` (the change's own header) or `feature-owned` (the fallback)
+  blast_any: ""            # truthy when EITHER half of the blast radius is non-empty
   fence_ok: "true"         # default green so the gate is a no-op when nothing downstream
   gate_decision: "clean"   # audit: 'clean' unless a RED fence was deliberately overridden
   # The change's own `## Depends on` vs its wave — the fence that keeps the number and the
@@ -186,12 +194,13 @@ vars:
   delta_model_exists: "false" # false ⇒ a behaviour-only change: the spec merge is the whole merge
   model_orphan: "false"       # a model delta whose context has no master to merge it into
   model_master_ok: "true"     # lowered by model_orphan_raise; the gate reads only this
-  # THE MERGE FENCE. All three flags default DOWN and are raised only by the good state, so
+  # THE MERGE FENCE. All four flags default DOWN and are raised only by the good state, so
   # a cr-merge-check that errored or a field that was renamed leaves the merge refused.
   # Fail-closed is the only safe default in front of an in-place edit of the masters.
   rebase_ok: "false"
   merged_open_ok: "false"
   no_blockers: "false"
+  wave_ordering_ok: "false"
   rebase_needed: "true"       # the raw readings, defaulted to the blocking value for the
   has_merged_open: "true"     # same reason — an unanswered question is not a clean answer
   has_blockers: "true"
@@ -200,7 +209,11 @@ vars:
   blocker_ids: ""
   blocker_count: "0"
   merged_open_ids: ""
-  merge_wave: "1"
+  wave_problem: ""            # which changes could not be ordered, and why that ends the check
+  unordered_ids: ""
+  unordered_count: "0"
+  merge_wave: ""              # EMPTY, not 1: an unreadable wave is not the floor, and the
+                              # gate below refuses rather than letting it pass as one
   snapshot_dir: ""            # changes/<id>/pre-merge/ — the before-image recall-delta restores
   snapshot_count: "0"
   # THE OKF OVERVIEW'S SUBJECT. The Overview step selects a `## Aggregate:` section BY
@@ -416,6 +429,10 @@ workflow:
       - { name: has_merged_open,  from: "$.has_merged_open" }
       - { name: merged_open_ids,  from: "$.merged_open_ids" }
       - { name: merge_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" }
 
   - id: rebase_ok_raise
     condition: "{{rebase_needed}} == false"
@@ -435,7 +452,21 @@ workflow:
     action: verify_context
     require_true: merged_open_ok
     on_false: stop
-    on_false_message: "finalize-delta REFUSED — {{merged_open_ids}} has already been MERGED into a master but not yet CLOSED, so the masters carry it while the version still reads {{current_version}}. That change may belong to ANOTHER feature in this context: domain-model.md is shared, so a sibling's merge moves a master this delta was authored against, and it is counted here when it touched an aggregate this delta also names. Change {{active_change}} was authored against those pre-merge masters and the version comparison cannot see the difference. Finish the merged change first: /appweaver analyze-slice then /appweaver close-delta {{merged_open_ids}}, which bumps the version — then rebase this one against the new number and re-run /appweaver finalize-delta {{active_change}}."
+    on_false_message: "finalize-delta REFUSED — a change has already been MERGED into a master but not yet CLOSED, so the masters carry it while the version still reads {{current_version}}: {{merged_open_ids}}. The feature named beside it is where it lives — domain-model.md is shared, so a SIBLING feature's merge moves a master this delta was authored against, and it is counted here when it touched an aggregate this delta also names. Change {{active_change}} was authored against those pre-merge masters and the version comparison cannot see the difference. Finish the merged change first, under ITS OWN feature: select that feature (/appweaver select-feature), then /appweaver analyze-slice and /appweaver close-delta on it, which bumps the version — then rebase this one against the new number and re-run /appweaver finalize-delta {{active_change}}."
+
+  # WAVE ORDERING IS A PRECONDITION OF THE FENCE BELOW, not a finding of it. The predecessor
+  # test is `their wave < mine`, and a wave that cannot be read used to answer that question
+  # as 1 — the floor — so an unstamped delta posed as a predecessor to everything above it,
+  # and an unstamped SUBJECT compared against nothing at all and sailed through. Neither
+  # showed up as a refusal, because both look exactly like "no blockers found".
+  # It is narrow by construction: nothing sits below the floor, so a change AT wave 1 is
+  # never held up by a neighbour nobody stamped. Above it, the fence says so instead of
+  # guessing.
+  - id: require_wave_ordering
+    action: verify_context
+    require_true: wave_ordering_ok
+    on_false: stop
+    on_false_message: "finalize-delta REFUSED — the wave fence cannot order change {{active_change}}, so it cannot tell you whether a predecessor is still open: {{wave_problem}}. A wave is stamped by a script and read by both merge gates; `**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 finalize-delta {{active_change}}. A change in another feature is stamped under that feature (/appweaver select-feature first)."
 
   - id: no_blockers_raise
     condition: "{{has_blockers}} == false"
@@ -445,7 +476,7 @@ workflow:
     action: verify_context
     require_true: no_blockers
     on_false: stop
-    on_false_message: "finalize-delta REFUSED — change {{active_change}} is at wave {{merge_wave}} and {{blocker_count}} open change(s) sit at a LOWER wave: {{blocker_ids}}. A lower wave is committed to landing FIRST, and this delta was planned with those in its context as the base it builds on — merging it now folds in behaviour that assumes a predecessor the masters do not yet carry. Merge and close the lower-wave change(s) first (/appweaver finalize-delta <CR-id> → analyze-slice → close-delta), then rebase and re-run this one. Same-wave changes are independent and are not counted here; if this delta does NOT in fact build on them, correct its `## Depends on` section (naming only the deltas it truly builds on) and re-run /appweaver specify's wave derivation — `.appweaver/scripts/bash/aw-spec-actions.sh cr-wave-derive --cr-id {{active_change}} --stamp` applies it directly."
+    on_false_message: "finalize-delta REFUSED — change {{active_change}} is at wave {{merge_wave}} and {{blocker_count}} open change(s) sit at a LOWER wave. A lower wave is committed to landing FIRST, and this delta was planned with those in its context as the base it builds on — merging it now folds in behaviour that assumes a predecessor the masters do not yet carry. THE LOWER-WAVE CHANGES: {{blocker_ids}}. This scan is context-wide, so one of them may belong to a feature you have never opened — and finalize-delta resolves a change under the ACTIVE feature. Select the feature named beside a change (/appweaver select-feature) before running /appweaver finalize-delta <CR-id> → analyze-slice → close-delta on it; then rebase and re-run this one. Same-wave changes are independent and are not counted here; if this delta does NOT in fact build on them, correct its `## Depends on` section (naming only the deltas it truly builds on) and re-run /appweaver specify's wave derivation — `.appweaver/scripts/bash/aw-spec-actions.sh cr-wave-derive --cr-id {{active_change}} --stamp` applies it directly."
 
   # THE DECLARED DEPENDENCIES AND THE WAVE MUST AGREE. The fence above orders changes by
   # their wave NUMBER; this one checks that number against what the change's own documents
@@ -472,15 +503,21 @@ workflow:
   #     its OKF Cross-References, TRANSITIVELY (C→B→A all count) and placeholder-filtered
   #     (the "_(none observed)_" row is NOT a dependent) = the real blast radius. If any
   #     slice does, this change could ripple into it, so run a SCOPED regression fence over
-  #     this feature + its downstream closure (--scope slice --also <closure>) BEFORE the
+  #     this feature + its blast radius (--scope slice --also <referrers> --also <co-owners>) BEFORE the
   #     doc merge, so a block leaves the repo untouched. The fence binds fence_GREEN (ran
   #     AND matched >=1), not raw ok, so an empty / zero-match run is RED, never a vacuous
   #     pass. If RED we do NOT hard-stop blindly: we WRITE a triage report, then surface the
-  #     failing log + dependent slices and ASK the developer — Abort (a real downstream
+  #     failing log + affected slices and ASK the developer — Abort (a real downstream
   #     break: fix it first) or, having reviewed the log (pre-existing / flaky / unrelated),
   #     deliberately Override and close anyway. Non-interactive / CI runs take the FIRST
   #     option (Abort), so automation never silently overrides. Skipped when nothing depends
-  #     on this slice (count 0) or the fence is green.
+  #     on this slice and nothing co-owns its aggregates, or the fence is green.
+  #     THE FENCE RUNS TESTS, so it takes the BUILT half of the closure. Edges are read off
+  #     the lane PLAN, not off code, so a dependant can be fully planned and hold none:
+  #     selecting it would hand the fence a slice with no tests, and the fence counts a
+  #     zero-match run as RED. An unbuilt dependant is still reported — it is a real
+  #     dependant with nothing to re-test yet, which is a different thing from being
+  #     unaffected, and it is what /appweaver implement on that feature will settle.
   - id: xref_impact
     action: execute_script
     on_error: continue
@@ -488,16 +525,49 @@ workflow:
     subcommand: list
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: downstream_count, from: "$.referrer_closure_count" }   # transitive + placeholder-filtered
-      - { name: downstream_csv,   from: "$.referrer_closure_csv" }     # blast-radius names → --also + display
+      - { name: downstream_count, from: "$.built_count" }              # transitive, placeholder-filtered, HAS CODE
+      - { name: downstream_csv,   from: "$.built_closure_csv" }        # blast-radius names → --also + display
+      - { name: unbuilt_count,    from: "$.unbuilt_count" }            # dependants planned but never implemented
+      - { name: unbuilt_csv,      from: "$.unbuilt_closure_csv" }
+      - { name: reached_count,    from: "$.referrer_closure_count" }   # the whole closure, for the report
+
+  # THE OTHER HALF OF THE BLAST RADIUS. A referrer reaches this aggregate through an edge;
+  # a CO-OWNER has no edge to it because it is not a user of the aggregate — it is one of
+  # the capabilities the aggregate is made of, and its code is in the very files this merge
+  # rewrites. `Encounter.cs` is extended by every feature claiming Encounter, so a change to
+  # it can break a co-owner while every referrer still passes. Scoped to the aggregates THIS
+  # delta names, so a feature owning two aggregates does not drag the second one's co-owners
+  # through a fence they cannot have been affected by.
+  - id: xref_co_owners
+    action: execute_script
+    on_error: continue
+    script: { ref: xref }
+    subcommand: co-owners
+    args: ["--cr", "{{active_change}}", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: co_owner_count,  from: "$.count" }
+      - { name: co_owner_csv,    from: "$.features_csv" }
+      - { name: co_owner_aggs,   from: "$.aggregates_csv" }
+      - { name: co_owner_source, from: "$.source" }
+
+  # The fence runs when EITHER half is non-empty. Two ordered assignments rather than one
+  # condition, because the dialect has no compound conditions.
+  - id: blast_from_referrers
+    condition: "{{downstream_count}} != 0"
+    action: set
+    vars: { blast_any: "true" }
+  - id: blast_from_co_owners
+    condition: "{{co_owner_count}} != 0"
+    action: set
+    vars: { blast_any: "true" }
 
   - id: run_downstream_fence
-    condition: "{{downstream_count}} != 0"
+    condition: "{{blast_any}}"
     action: execute_script
     on_error: continue
     script: { ref: actions }
     subcommand: test-run
-    args: ["--feature-dir", "{{feature_dir}}", "--scope", "slice", "--also", "{{downstream_csv}}"]
+    args: ["--feature-dir", "{{feature_dir}}", "--scope", "slice", "--also", "{{downstream_csv}}", "--also", "{{co_owner_csv}}"]
     outputs:
       - { name: fence_ok,   from: "$.fence_green" }
       - { name: fence_tool, from: "$.tool" }
@@ -511,11 +581,14 @@ workflow:
   # only when nothing depends on this slice (no fence ran, nothing to report).
   - id: ctx_broken_downstream
     action: build_context
-    condition: "{{downstream_count}} != 0"
+    condition: "{{blast_any}}"
     vars:
       active_change: "{{active_change}}"
       downstream_count: "{{downstream_count}}"
       downstream_csv: "{{downstream_csv}}"
+      co_owner_count: "{{co_owner_count}}"
+      co_owner_csv: "{{co_owner_csv}}"
+      co_owner_aggs: "{{co_owner_aggs}}"
       fence_ok: "{{fence_ok}}"
       fence_log: "{{fence_log}}"
     context:
@@ -526,14 +599,27 @@ workflow:
       - { path: "{{delta_backend_plan}}", optional: true }
   - id: write_broken_downstream
     action: agent_author
-    condition: "{{downstream_count}} != 0"
+    condition: "{{blast_any}}"
     include_standards: false                       # a triage report, not generated code
     output_target: { type: file, path: "{{feature_dir}}/changes/{{active_change}}/broken-downstream.md" }
     task: |
       Author the DOWNSTREAM report for change {{active_change}}: the result of re-running this
-      change against the aggregates that DEPEND ON this feature. finalize-delta does NOT fix a
-      downstream slice (that is the downstream slice's own job). Downstream blast radius
-      ({{downstream_count}}): {{downstream_csv}}. The fence result was fence_green={{fence_ok}}
+      change against everything it could have broken. finalize-delta does NOT fix a
+      downstream slice (that is the downstream slice's own job).
+      THE BLAST RADIUS HAS TWO HALVES and they fail for different reasons — say which is which
+      wherever the report names a slice:
+      - DEPENDENTS ({{downstream_count}}): {{downstream_csv}} — aggregates that USE this one
+        through a Cross-Reference edge. A failure here is a broken CONTRACT between two slices.
+      - NOT YET BUILT ({{unbuilt_count}}): {{unbuilt_csv}} — aggregates that also depend on this
+        one and hold no code yet, so the fence had nothing to run for them. Edges come from the
+        lane PLAN, so these are real dependants whose contract with this aggregate has never
+        been exercised. Say so plainly: they were NOT tested, which is not the same as passing,
+        and /appweaver implement on those features is what settles them.
+      - CO-OWNERS ({{co_owner_count}}): {{co_owner_csv}} — features that share the aggregate(s)
+        this change touches ({{co_owner_aggs}}). They hold no edge to it: their code is IN the
+        files this merge rewrites, so a failure here is this change breaking a sibling
+        capability of the same aggregate, not a contract between two of them.
+      Either list may be empty. The fence result was fence_green={{fence_ok}}
       (true = every downstream test passed; false = at least one failed). Test log:
       {{fence_log}}
       Always write the file (it is regenerated on every finalize-delta run so a green close never
@@ -541,8 +627,9 @@ workflow:
 
       IF fence_green is TRUE (all passed): write a SHORT all-clear — the heading
       `# Broken Downstream — change {{active_change}}`, then a few lines stating that the
-      {{downstream_count}} slice(s) that use this feature ({{downstream_csv}}) were re-run against
-      this change and all passed, so nothing downstream broke. No per-slice sections; invent nothing.
+      {{downstream_count}} dependent slice(s) ({{downstream_csv}}) and {{co_owner_count}} co-owner
+      feature(s) ({{co_owner_csv}}) were re-run against this change and all passed, so nothing it
+      could reach broke. No per-slice sections; invent nothing.
 
       IF fence_green is FALSE (something failed): write the triage record —
       - `# Broken Downstream — change {{active_change}}` and a one-line statement: aggregates that
@@ -550,10 +637,11 @@ workflow:
         finalize-delta's downstream gate. Note it is the record a human reads while deciding Abort vs
         Override, and if the change is Overridden it is archived with the change as the record of
         what was knowingly closed over.
-      - A SUMMARY line: total downstream slices in the blast radius, and how many have a failing test.
-      - One `##` section per DOWNSTREAM slice that has a failing test — attribute a failure to a
-        slice by matching the failing test names in the log to the slice's name. Under it, on their
-        own labelled lines: the downstream aggregate, the failing test(s) named in the log, what
+      - A SUMMARY line: total slices in the blast radius (dependents + co-owners), and how many have a failing test.
+      - One `##` section per slice with a failing test, from EITHER half — attribute a failure to a
+        slice by matching the failing test names in the log to the slice's name, and label the
+        section `dependent` or `co-owner`. Under it, on their
+        own labelled lines: the aggregate or feature, the failing test(s) named in the log, what
         broke (as far as the log shows), and a RESOLUTION line — either this change broke the
         downstream slice's expected contract (fix it in the downstream slice's OWN CR, or re-baseline
         its golden-master) or the failure is pre-existing / flaky / unrelated (a candidate for a