aw-spec-cli 0.1.20 → 0.1.21

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.
@@ -128,9 +163,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 +292,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 +350,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 +515,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
@@ -422,7 +628,12 @@ workflow:
       - { name: referrer_count, from: "$.referrer_closure_count" }
       - { name: referrer_names, from: "$.referrer_closure" }
 
+  # 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 +642,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 +667,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: |
@@ -488,7 +705,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 +762,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 +807,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

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

@@ -40,10 +40,10 @@
 # drift. What this stage must NOT do is hide that by merging a delta plan: the plan would
 # then agree with the spec without any run of `plan` ever having derived it.
 #
-# ✅ THE DETECTION IS BUILT (2026-09-14). analyze-plan leaves `.aw-plan-gate.json` when it
-# PASSES — the sha256 of spec.md, the context's domain-model.md and each lane plan it read —
-# and `implement` reads it through plan-gate-check before any lane generates, refusing a
-# master run whose plans are no longer the ones the gate passed. So after this merge the
+# ✅ THE DETECTION IS BUILT (2026-09-14). Every master-mode analyze-plan run leaves
+# `.aw-plan-gate.json` — the sha256 of spec.md, the context's domain-model.md and each lane
+# plan it read, and its verdict — and `implement` reads it through plan-gate-check before any
+# lane generates, refusing a master run whose plans are no longer the ones the gate checked. So after this merge the
 # plans are not merely "visibly behind": the next `implement` on the master path says so and
 # stops, naming `plan main`. A feature with no receipt has never been gated since the receipt
 # existed and is reported, never refused.
@@ -94,17 +94,33 @@
 #   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
 #   spec.md no longer says, and merging them is last-writer-wins over work that landed.
+#   cr-rebase runs FIRST and re-stamps that header — and `**Base context version**` — when
+#   the move is one this delta survives: the masters moved, and everything that landed in
+#   between touched OTHER aggregates than the ones this delta names. Nothing else in the kit
+#   could ever write those headers, so before this the only way past the refusal was a hand
+#   edit the authoring prompts forbid. Where a landed change DOES share an aggregate, the
+#   stamp is left alone and the refusal below names it.
 #
 #   MERGED-NOT-CLOSED. The masters can move WITHOUT the version moving, because this stage
-#   merges and close-delta bumps. In that window spec.md carries a change the number does not
-#   reflect, so a sibling sharing the same base_version compares EQUAL and would merge onto
-#   masters that had already shifted. The version alone is not a proxy for "the masters
-#   moved"; the id appearing in spec.md is the other half of the answer.
+#   merges and close-delta bumps. In that window the masters carry a change the number does
+#   not reflect, so a sibling sharing the same base_version compares EQUAL and would merge
+#   onto masters that had already shifted. The version alone is not a proxy for "the masters
+#   moved"; a Change History row naming the change is the other half of the answer. That test
+#   lives in aw-crstate — one definition for this fence, cr-recall-check and close-delta —
+#   and it reads the CR CELL of a row, not the id anywhere in the file, which used to fire on
+#   an id quoted in prose. It looks at the context model too, which every feature shares, so
+#   a SIBLING feature's merged-unclosed change is visible; a sibling counts only where it
+#   touched an aggregate this delta also names.
 #
 #   PREDECESSOR. A lower wave is committed to landing first, and `plan` put exactly those
-#   deltas in this one's context as the base it was planned on top of. `depends_on` is
-#   stamped nowhere, so the wave is the only dependency signal that exists — and it is the
-#   conservative one, since same-wave changes are independent by definition.
+#   deltas in this one's context as the base it was planned on top of. Same-wave changes are
+#   independent by definition, so the wave is the conservative signal.
+#
+#   DECLARED DEPENDENCIES vs THE WAVE. The wave is a number; `## Depends on` in the change's
+#   own delta documents is what that number is supposed to encode. specify derives the wave
+#   from that section, and this stage re-checks it (cr-wave-derive): a change naming a
+#   predecessor at the same or a higher wave contradicts itself, and the predecessor fence
+#   above — which sees only numbers — would let the two merge in either order.
 #
 # All three are RAISE-then-VERIFY and fail-closed: each flag is raised only by the good
 # state, so a check that did not run leaves the merge refused rather than waved through.
@@ -153,6 +169,17 @@ vars:
   downstream_csv: ""       # the blast-radius names, fed to the scoped fence's --also and shown to the human
   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
+  # prose from drifting apart. Defaults green, so a run that cannot read them is not blocked.
+  wave_ok: "true"
+  wave_required: ""
+  wave_message: ""
+  # The automatic rebase (cr-rebase). Defaults say "nothing moved, nothing stamped",
+  # so a step that could not run leaves the existing refusal to speak.
+  rebase_clean: "false"
+  rebase_stamped: ""
+  rebase_conflicts: ""
+  rebase_message: ""
   domain_model: ""            # specs/<Context>/domain-model.md — the second merge target
   domain_model_exists: "false"
   delta_model: ""             # specs/<Context>/domain-model.<id>.delta.md — the model half of the change
@@ -352,6 +379,28 @@ workflow:
   #     NO on_error: continue. A gate that cannot run must not be a gate that passes, and the
   #     raise-then-verify below is fail-closed for the same reason: each flag is raised ONLY
   #     by the good state, so a field that never arrived leaves it down and the merge refuses.
+  # AUTO-REBASE FIRST, and only where it is EARNED. `**Base version**` was written once by
+  # cr-setup and nothing could ever update it — every other site reads it, and every
+  # authoring prompt forbids the model from writing it — so a moved master left the operator
+  # hand-editing the delta-spec in the middle of an automated loop. cr-rebase re-stamps it
+  # (and `**Base context version**`, which until now nothing read at all) when the masters
+  # moved and NOTHING THAT LANDED IN BETWEEN touched the aggregates this delta names: then
+  # the delta still describes the document it was written against, and the stamp is
+  # bookkeeping. A landed change sharing an aggregate, or one whose model delta cannot be
+  # read, leaves the stamp alone — and the refusal below fires with the overlap named.
+  # It runs BEFORE cr-merge-check so that check reads the stamp this step just settled.
+  - id: auto_rebase
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: cr-rebase
+    args: ["--cr-id", "{{active_change}}", "--feature-dir", "{{feature_dir}}", "--stamp"]
+    outputs:
+      - { name: rebase_clean,     from: "$.clean" }
+      - { name: rebase_stamped,   from: "$.stamped" }
+      - { name: rebase_conflicts, from: "$.conflict_ids" }
+      - { name: rebase_message,   from: "$.message" }
+
   - id: merge_check
     action: execute_script
     script: { ref: actions }
@@ -376,7 +425,7 @@ workflow:
     action: verify_context
     require_true: rebase_ok
     on_false: stop
-    on_false_message: "finalize-delta REFUSED — change {{active_change}} needs a REBASE. It was authored against master version {{base_version}}, and the feature now stands at {{current_version}}: another change finalized and closed while this one was open. Its MODIFIED items name a BEFORE that spec.md no longer says, so merging now would overwrite work that already landed. Rebase: run /appweaver analyze-plan-delta {{active_change}} against the current master, fix what it reports, re-stamp the delta's `**Base version**:` to {{current_version}}, then re-run /appweaver finalize-delta {{active_change}}."
+    on_false_message: "finalize-delta REFUSED — change {{active_change}} needs a REBASE. It was authored against master version {{base_version}}, and the feature now stands at {{current_version}}: another change finalized and closed while this one was open. Its MODIFIED items name a BEFORE that spec.md no longer says, so merging now would overwrite work that already landed. The automatic re-stamp did not apply, because what landed in between touches this delta's own aggregates: {{rebase_message}}. Rebase for real: run /appweaver analyze-plan-delta {{active_change}} against the current master, fix what it reports — then `.appweaver/scripts/bash/aw-spec-actions.sh cr-rebase --cr-id {{active_change}} --stamp` re-stamps `**Base version**` and `**Base context version**` once the overlap with {{rebase_conflicts}} is resolved, and /appweaver finalize-delta {{active_change}} can run again."
 
   - id: merged_open_ok_raise
     condition: "{{has_merged_open}} == false"
@@ -386,7 +435,7 @@ 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 spec.md but not yet CLOSED, so the masters carry it while the version still reads {{current_version}}. 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 — {{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}}."
 
   - id: no_blockers_raise
     condition: "{{has_blockers}} == false"
@@ -396,7 +445,28 @@ 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, /appweaver cr-wave can correct its wave."
+    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."
+
+  # 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
+  # SAY under `## Depends on`. Before this, the two could diverge silently: an author named
+  # a predecessor in prose, cr-setup left the wave at the predecessor's own level, and the
+  # fence above then read the two as independent and let them merge in either order.
+  - id: wave_declared_check
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: cr-wave-derive
+    args: ["--cr-id", "{{active_change}}"]
+    outputs:
+      - { name: wave_ok,       from: "$.ok" }
+      - { name: wave_required, from: "$.required_wave" }
+      - { name: wave_message,  from: "$.message" }
+  - id: require_wave_matches_depends
+    action: verify_context
+    require_true: wave_ok
+    on_false: stop
+    on_false_message: "finalize-delta REFUSED — change {{active_change}} contradicts its own `## Depends on`: {{wave_message}}. The blocker fence above compares wave NUMBERS, so it would let the two merge in either order and this delta could land before the change it says it builds on. Either raise this change to wave {{wave_required}} (`.appweaver/scripts/bash/aw-spec-actions.sh cr-wave-derive --cr-id {{active_change}} --stamp`, which reads the same section), or correct `## Depends on` in its delta documents if it does not in fact build on them."
 
   # 1c. DOWNSTREAM GATE (hard, with a REVIEWED override). Who depends on this aggregate —
   #     its OKF Cross-References, TRANSITIVELY (C→B→A all count) and placeholder-filtered
@@ -701,7 +771,7 @@ workflow:
   #     the context has no model: there would be nothing in context to distil, and a
   #     query with no source invents one. Best-effort; an empty answer is a no-op.
   # WHICH AGGREGATE SECTION(S) THIS CHANGE ACTUALLY TOUCHED, read off the model delta's
-  # own `## Aggregate:` headings rather than assumed from the feature name. The Overview
+  # own `**Aggregates touched**:` header rather than assumed from the feature name. The Overview
   # step below selects a section by name, and a feature whose name is not an aggregate
   # name — one capability over a shared aggregate — selects nothing, producing an empty
   # answer that the writer then declines. Driving it off the delta's declared aggregates
@@ -830,6 +900,10 @@ outputs:
   # the change by close-delta. What an un-merge would restore from.
   pre_merge_snapshot: "{{snapshot_dir}}"
   base_version: "{{base_version}}"
+  # What the automatic rebase did before the fence read the stamp — empty when the delta was
+  # already current, and the reason it could not when a landed change shared its aggregates.
+  rebased: "{{rebase_stamped}}"
+  rebase_note: "{{rebase_message}}"
   model_merged: "{{delta_model_exists}}"      # true ⇒ domain-model.md was the second target of this merge.
                                               # false = a behaviour-only change: the spec merge was the
                                               # whole merge, not a half of one.