aw-spec-cli 0.1.20 → 0.1.21

package/assets/.appweaver/ORCH-DIALECT.md

@@ -90,7 +90,7 @@ the raw object, not its JSON string.
 | `set` | engine | assign vars (`vars:` or decl-style `parameters:`); raw-object aware |
 | `build_context` | engine | REPLACE the per-request envelope: `system:`/`context:` file lists (+ `context_from: <var>` holding paths a prior generation reported, + `vars:`) |
 | `load_standards` | engine | F4 — append to the **sticky standards set** prepended to every system block (dedup, `optional:`, `files:`/`files_from_variable`). This is the byte-stable, prompt-cacheable prefix |
-| `execute_script` | engine | F1 — run a `scripts:` ref (`subcommand:` + `args:`; sh/ps1 via `--os`); stdout's last line = JSON, bound via `outputs[]`; `on_error: continue` tolerated; cached across resumes; runs for real even in mock transport |
+| `execute_script` | engine | F1 — run a `scripts:` ref (`subcommand:` + `args:`; sh/ps1 via `--os`); stdout's last line = JSON, bound via `outputs[]`; `on_error: continue` tolerates a script that ran and exited non-zero (its outputs bind empty) — never an undeclared ref, which the pre-flight refuses before step 1; cached across resumes; runs for real even in mock transport |
 | `verify_context` | engine | F2 — gates: `required_files` (+`allow_missing`), `require_non_empty` (+`on_empty[_message]`), `require_true` (+`on_false[_message]`), `require_value`+`equals` (+`on_mismatch[_message]`). `stop` raises a terminal stop |
 | `agent_generate` | fresh agent | demo contract (code work): agent DECIDES file paths per the loaded standards, writes with its tools, reports `files[]` in the trailing ```json fence. `sdk-apply` = read-only generation + invoking agent applies |
 | `agent_review` | fresh agent | payload-only review of `review_of_var`/`review_of` files (inlined into THIS request, never sticky) → `{pass, issues}` |
@@ -159,8 +159,13 @@ orchestrator.py <workflow.orch.yaml>
 ## Validation & smoke
 
 - `--validate` every workflow/module (unknown actions/strategies, duplicate
-  ids, script refs + files on disk, `output_target.path`, module paths,
-  unproduced `{{vars}}`, dialect header).
+  ids, script refs + files on disk — including the refs of every included
+  module, which resolve against the caller's `scripts:` — `output_target.path`,
+  module paths, unproduced `{{vars}}`, dialect header).
+- Every run starts with the same checks. A workflow with an ERROR is not
+  started: the engine exits 1 with `status: stopped` and the defects in the
+  reason, before any step runs and before a checkpoint response is ingested.
+  Warnings never block.
 - `workflows/_smoke.orch.yaml` exercises every construct with no model and no
   writes outside `.smoke-out`: run it `--non-interactive` (CI) and with
   `--checkpoint` (protocol walk-through).

package/assets/.appweaver/orchestrator/modules/delta-spec.orch.yaml

@@ -140,7 +140,7 @@ workflow:
         touches the same aggregate or the same FR ids, say so under "Other open deltas"
         in Impact. If THIS change only makes sense after one of them lands, say so in the
         Wave rationale — that is a wave dependency, and the wave must then be RAISED above
-        that delta's (report it; `cr-wave` applies it). Do not silently assume their
+        that delta's — name it under `## Depends on` and the wave is raised from that. Do not silently assume their
         changes: until merged they are proposals, not the master.
       - Do NOT edit the Wave / Created / Base version headers — scripts stamp those.
       Change request: {{USER_INPUT}}
@@ -183,4 +183,25 @@ workflow:
         entry MUST sit in a LOWER wave than this delta ({{wave}}). "None" when it stands
         alone. Reading another delta is NOT depending on it — only assuming its changes is.
       - Do NOT edit the Wave / Created / Base context version headers — scripts stamp those.
+        Naming a delta under "## Depends on" is what RAISES this change's wave, immediately
+        after you write it; you never set the number yourself.
       Change request: {{USER_INPUT}}
+
+  # 4. THE WAVE THE DOCUMENTS THEMSELVES IMPLY. cr-setup stamped a provisional wave before
+  #    either half existed — the highest already open, which is right for a change that
+  #    stands alone and wrong for one that builds on another: it lands at its predecessor's
+  #    wave, where the blocker fence reads the two as independent and lets them merge in
+  #    either order. Now that "## Depends on" is written, that declaration decides: the wave
+  #    is raised to one above the highest delta named there, in BOTH halves, so the number
+  #    and the prose cannot drift apart. A change that names none keeps what it has, and one
+  #    already sitting higher is left alone. The merge fence re-checks the same rule.
+  - id: derive_wave
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: cr-wave-derive
+    args: ["--cr-id", "{{cr_id}}", "--stamp"]
+    outputs:
+      - { name: wave,         from: "$.wave" }
+      - { name: wave_depends, from: "$.depends_on" }
+      - { name: wave_message, from: "$.message" }

package/assets/.appweaver/orchestrator/orchestrator.py

@@ -1458,6 +1458,39 @@ def _refs_in(v):
     return found
 
 
+def _module_script_refs(mpath, base_dir, seen):
+    """(step id, script ref) for every execute_script step an included module runs,
+    following nested includes. Modules that cannot be read contribute nothing — the
+    include check already warns about a module missing from disk."""
+    path = next((c for c in (mpath, os.path.join(base_dir, mpath)) if c and os.path.exists(c)), "")
+    if not path or path in seen:
+        return []
+    seen.add(path)
+    try:
+        with open(path, encoding="utf-8") as fh:
+            mwf = load_yaml(fh.read())
+    except Exception:
+        return []
+    out = []
+
+    def walk(ss):
+        for s in ss or []:
+            if not isinstance(s, dict):
+                continue
+            p = s.get("parameters") or s
+            if s.get("action") == "execute_script":
+                ref = (p.get("script") or {}).get("ref")
+                if ref:
+                    out.append((s.get("id") or "step", ref))
+            elif s.get("action") == "include" and s.get("module"):
+                out.extend(_module_script_refs(s["module"], base_dir, seen))
+            elif s.get("action") == "loop":
+                walk(s.get("steps"))
+
+    walk((mwf or {}).get("workflow"))
+    return out
+
+
 def validate_workflow(wf, base_dir):
     errors, warnings = [], []
     if not isinstance(wf, dict):
@@ -1551,6 +1584,13 @@ def validate_workflow(wf, base_dir):
                 errors.append(f"{loc}: include needs 'module'")
             elif not (os.path.exists(m) or os.path.exists(os.path.join(base_dir, m))):
                 warnings.append(f"{loc}: include module not found on disk: {m}")
+            elif scripts:
+                # A module declares no scripts: of its own — its refs resolve against
+                # THIS workflow's map, so an undeclared one is this workflow's defect.
+                for mid, ref in _module_script_refs(m, base_dir, set()):
+                    if ref not in scripts:
+                        errors.append(f"{loc}: included step {mid} uses script ref "
+                                      f"'{ref}', not declared in top-level scripts:")
         if action == "agent_query" and not step.get("outputs"):
             warnings.append(f"{loc}: agent_query has no outputs[] to bind")
         if action == "agent_author" and not (p.get("output_target") or {}).get("path"):
@@ -1682,6 +1722,31 @@ def main(argv=None):
             print(f"\n{opts.workflow}: {len(errors)} error(s), {len(warnings)} warning(s)")
         return 1 if errors else 0
 
+    # ---- pre-flight: a workflow --validate rejects is never started ----------
+    # An undeclared script ref, an unknown action or a duplicate step id is a defect in
+    # the workflow file, and no run can recover from it — `on_error: continue` covers a
+    # script that RAN and failed, not one the workflow never declared. Found mid-run, it
+    # strands the operator after the questions were answered; found here, nothing has
+    # happened yet. Runs BEFORE the checkpoint ingest, so a refused resume leaves the
+    # pending response on disk for the run after the fix. Warnings do not block.
+    try:
+        with open(opts.workflow, encoding="utf-8") as fh:
+            wf = load_yaml(fh.read())
+        errors, _ = validate_workflow(wf, os.path.dirname(os.path.abspath(opts.workflow)))
+    except Exception as e:
+        wf, errors = None, [f"parse: {e}"]
+    if errors:
+        reason = (f"workflow {opts.workflow} has {len(errors)} defect(s) and was not started: "
+                  + "; ".join(errors)
+                  + " — fix the workflow file (python3 .appweaver/orchestrator/orchestrator.py "
+                  "<workflow> --validate lists them) and re-run.")
+        if opts.json:
+            print(json.dumps({"status": "stopped", "reason": reason, "errors": errors}, indent=2))
+        else:
+            print("\n=== STOPPED ===")
+            print(reason)
+        return 1
+
     # ---- checkpoint mode: load prior state + ingest the agent's response ----
     # (before profile/strategy resolution, so a bare `--checkpoint` resume
     # restores the original run's profile/strategy/model/os and prefills)
@@ -1787,9 +1852,6 @@ def main(argv=None):
         print("ERROR: --transport real needs --strategy (or --agent-profile / --checkpoint)")
         return 2
 
-    with open(opts.workflow, encoding="utf-8") as fh:
-        wf = load_yaml(fh.read())
-
     orch = Orchestrator(wf, opts)
     try:
         result = orch.run()

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

@@ -36,8 +36,8 @@
 # is visible so it can be designed around, and building on it silently is the defect this
 # check exists to catch.
 #
-# OVERLAP IS COMPUTED, NOT ASKED. cr-overlap reads the `## Aggregate:` headings of every
-# pending model delta and reports which other open changes touch the same aggregates.
+# OVERLAP IS COMPUTED, NOT ASKED. cr-overlap reads the `**Aggregates touched**:` header of
+# every pending model delta and reports which other open changes touch the same aggregates.
 # That is a fact about two files, so a regex answers it exactly and the result is handed
 # to the model as a finding rather than as a question.
 #
@@ -229,9 +229,9 @@ workflow:
       - { name: sibling_count,             from: "$.sibling_count" }
       - { name: domain_model,              from: "$.domain_model" }
 
-  # 3b. WHICH OTHER OPEN CHANGES TOUCH THE SAME AGGREGATES. Deterministic: the
-  #     `## Aggregate:` headings of the pending model deltas are the merge unit
-  #     domain-model.md is organised by, so this is a regex over two files rather than a
+  # 3b. WHICH OTHER OPEN CHANGES TOUCH THE SAME AGGREGATES. Deterministic: each pending
+  #     model delta's `**Aggregates touched**:` header names the `## Aggregate:` sections
+  #     of domain-model.md it merges into, so this is a regex over two files rather than a
   #     judgement. The result reaches the check below as a FINDING, not a question.
   - id: cr_overlap
     action: execute_script
@@ -645,7 +645,7 @@ workflow:
     action: verify_context
     require_true: analyze_ok
     on_false: stop
-    on_false_message: "The delta plans for {{cr_id}} do not realise the delta spec (gaps: {{analyze_gaps}}) — repair was skipped (see {{cr_dir}}/delta-plan-analyze-report.md), or it could not be reconciled in 3 passes. A 'LIFT-FAILURE:' gap means a domain constraint from the gate checklist was never lifted into the delta spec, and a `model` gap means a plan needs structure the effective model does not define — both are fixed by /appweaver specify, which authors the delta spec and the model delta; this gate may not write either. A `wave` gap is closed by declaring '## Depends on' (and raising the wave with cr-wave) or by planning around the sibling. Otherwise fix out of band, or re-run and choose Repair."
+    on_false_message: "The delta plans for {{cr_id}} do not realise the delta spec (gaps: {{analyze_gaps}}) — repair was skipped (see {{cr_dir}}/delta-plan-analyze-report.md), or it could not be reconciled in 3 passes. A 'LIFT-FAILURE:' gap means a domain constraint from the gate checklist was never lifted into the delta spec, and a `model` gap means a plan needs structure the effective model does not define — both are fixed by /appweaver specify, which authors the delta spec and the model delta; this gate may not write either. A `wave` gap is closed by declaring '## Depends on' — which is what sets the wave, since specify derives it from that section and the merge fence re-checks it — or by planning around the sibling. Otherwise fix out of band, or re-run and choose Repair."
 
   # 8. Post-execution hooks.
   - id: resolve_post_hooks

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

@@ -30,7 +30,8 @@
 # and that is the act a change in flight forbids — the delta docs are the authoritative
 # edit and the masters must not drift out from under them before finalize-delta merges.
 #   MASTER mode  (no change open) — the full gate: check, ask, repair, and STOP on gaps
-#                that could not be reconciled. spec.md + the lane plans are the masters.
+#                a plan rewrite could have closed but did not. spec.md + the lane plans
+#                are the masters.
 #   REPORT mode  (a change is open) — the same checks, read-only: no ask, no repair, no
 #                stop. It writes plan-analyze-report.md and routes on. The plans are
 #                DERIVED from spec.md + domain-model.md, so after finalize-delta merged a
@@ -40,6 +41,18 @@
 # to be stale, and a stage that refuses to look is not a gate. It reports; it never writes
 # a plan.
 #
+# TWO KINDS OF GAP, SPLIT BY WHO CAN CLOSE THEM (plan-gaps). A PLAN gap is closed by
+# rewriting a lane plan, which this stage may do. A ROUTED gap can only be closed in
+# spec.md or domain-model.md, which this stage may not write: a LIFT-FAILURE (a domain
+# constraint the spec never lifted), structure the model does not define, behaviour the
+# spec does not describe. Only plan gaps drive the repair loop and the stop; routed gaps
+# are reported and handed to /appweaver specify. Stopping on them would stop every feature
+# whose spec missed a constraint, with no repair this stage could ever make.
+#
+# EVERY MASTER RUN LEAVES A RECEIPT (.aw-plan-gate.json), green or not: the bytes it
+# checked and the verdict — conformant, routed-gaps or gaps. implement reads it and
+# refuses moved bytes or `gaps`, and warns on `routed-gaps`.
+#
 # WHICH MODE IS READ FROM THE DIRECTORY, AND DEFAULTS TO REPORT. changes/<id>/ is the
 # evidence (cr-list), not active_version.json's `active_change` — the ledger is the most
 # recently OPENED change and a crashed run can leave the two disagreeing. The permission to
@@ -60,7 +73,7 @@
 
 name: aw-spec-analyze-plan
 description: The spec↔plan conformance gate for every declared lane — confirm backend-plan.md and frontend-plan.md follow spec.md, that they bind to each other's contract, and that neither contradicts the bounded context's domain model (domain overlays are a backstop); with approval, repair the drifting plan. Lanes come from .appweaver/stacks.json, so one command gates backend-only, frontend-only and full-stack projects. Runs in one of two modes, decided from the changes/ directory rather than the ledger and defaulting to the read-only one — MASTER (no change open) checks, repairs on approval and stops on unreconciled gaps; REPORT (a change open) runs the same checks read-only and writes plan-analyze-report.md without asking, repairing or stopping, because the master plans may not be rewritten while a delta is in flight. It never opens, merges or closes a change.
-version: 3.2.0
+version: 3.3.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -68,6 +81,9 @@ scripts:
   actions:
     sh:  .appweaver/scripts/bash/aw-spec-actions.sh
     ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+  xref:
+    sh:  .appweaver/scripts/bash/aw-xref.sh
+    ps1: .appweaver/scripts/powershell/aw-xref.ps1
 
 standards:
   - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
@@ -87,8 +103,15 @@ vars:
   no_open_change: "false"  # RAISED only by cr-list answering that nothing is open
   gate_mode: "report"      # report | master — reported in the outputs
   may_repair: "false"      # the ask, the repair loop and the conformance stop are MASTER-only
-  gate_ok: "false"         # raised by a conformant run OR by report mode, which cannot repair
-  stamp_receipt: "false"   # master mode AND conformant ⇒ leave the receipt implement reads
+  gate_ok: "false"         # raised by a run with no plan gap left OR by report mode, which cannot repair
+  stamp_receipt: "false"   # master mode ⇒ leave the receipt implement reads, whatever the verdict
+  # THE GAP SPLIT, from plan-gaps after each analyze pass. Defaulted to the refusing
+  # answer, so a classification that never arrived neither ends the loop nor passes.
+  plan_ok: "false"         # no gap left that a plan rewrite closes
+  gate_verdict: "gaps"     # conformant | routed-gaps | gaps
+  plan_gap_count: "0"
+  routed_gaps: "[]"        # the gaps only /appweaver specify can close
+  routed_csv: ""
   receipt_file: ""
   receipt_gated: ""
   receipt_count: "0"
@@ -358,19 +381,20 @@ workflow:
       - { path: "{{be_plan_ctx}}", optional: true }
       - { path: "{{fe_plan_ctx}}", optional: true }
 
-  # 5. Conformance + REPAIR loop (spec is the anchor): check → REPORT gaps + ASK →
-  #    Repair on approval → re-check; "Report and Skip" writes plan-analyze-report.md
-  #    and stops. Bounded (3×). The repair is PER LANE, so a frontend drift never
-  #    rewrites a conformant backend plan.
+  # 5. Conformance + REPAIR loop (spec is the anchor): check → split the gaps → REPORT +
+  #    ASK → Repair on approval → re-check; "Report and Skip" writes plan-analyze-report.md
+  #    and stops. Bounded (3×). The loop runs while a PLAN gap is open: once only routed
+  #    gaps remain there is nothing a repair can change. The repair is PER LANE, so a
+  #    frontend drift never rewrites a conformant backend plan.
   - id: analyze_loop
     action: loop
-    while: "{{analyze_ok}} != true"
+    while: "{{plan_ok}} != true"
     max_iterations: 3
     steps:
       - id: analyze
         action: agent_query
         include_standards: true            # the gate overlays (checklist) are in the standards
-        schema: { ok: true, backend_repair: false, frontend_repair: false, gaps: [ { severity: "high", check: "<spec-backend|spec-frontend|contract|model|overlay>", lane: "<backend|frontend>", spec_ref: "<FR/BR/CN/DC/IC/UX/US/SC or overlay or —>", where: "<plan section>", gap: "<how it drifts>" } ] }
+        schema: { ok: true, backend_repair: false, frontend_repair: false, gaps: [ { severity: "high", check: "<spec-backend|spec-frontend|contract|model|overlay>", lane: "<backend|frontend>", route: "<plan|specify>", spec_ref: "<FR/BR/CN/DC/IC/UX/US/SC or overlay or —>", where: "<plan section>", gap: "<how it drifts>" } ] }
         mock: { ok: true, backend_repair: false, frontend_repair: false, gaps: [] }
         task: |
           spec.md is the ANCHOR. Gate this feature's LANE PLANS against it and against the
@@ -444,15 +468,37 @@ workflow:
           /appweaver specify, not the plan — do not fabricate it here).
 
           Tag every gap with its `check` and the `lane` whose document must change to close
-          it. Set backend_repair true if any gap needs the backend plan rewritten, and
-          frontend_repair likewise. (If a plan is still the empty template, treat the WHOLE
-          spec as gaps against it.) Set ok=true ONLY when every applicable check passes and
-          no checklist constraint is unaccounted for.
+          it, and with its `route` — who can close it:
+          - route `specify` when ONLY spec.md or domain-model.md can close it: every
+            LIFT-FAILURE; a plan element needing an aggregate, entity, event or invariant
+            the model does not define; a state or behaviour the plan needs that the spec
+            does not describe and no DA-n records.
+          - route `plan` for everything a rewrite of a lane plan closes: a missing plan
+            home, a name that differs from the model's, an invariant restated instead of
+            cited, a contract binding, an element with no spec basis.
+          Set backend_repair true if any `plan`-route gap needs the backend plan rewritten,
+          and frontend_repair likewise. (If a plan is still the empty template, treat the
+          WHOLE spec as gaps against it.) Set ok=true ONLY when every applicable check
+          passes and no checklist constraint is unaccounted for.
         outputs:
           - { name: analyze_ok,      from: "$.ok" }
           - { name: analyze_gaps,    from: "$.gaps" }
           - { name: backend_repair,  from: "$.backend_repair" }
           - { name: frontend_repair, from: "$.frontend_repair" }
+
+      # WHO CAN CLOSE EACH GAP, decided by script from the tags above: a LIFT-FAILURE is
+      # routed to specify whatever its tag says, and an untagged gap is a plan gap.
+      - id: classify_gaps
+        action: execute_script
+        script: { ref: actions }
+        subcommand: plan-gaps
+        args: ["--gaps", "{{analyze_gaps}}"]
+        outputs:
+          - { name: plan_ok,        from: "$.plan_ok" }
+          - { name: gate_verdict,   from: "$.verdict" }
+          - { name: plan_gap_count, from: "$.plan_gaps" }
+          - { name: routed_gaps,    from: "$.routed" }
+          - { name: routed_csv,     from: "$.routed_csv" }
       - id: conform_break
         action: break
         condition: "{{analyze_ok}} == true"
@@ -495,12 +541,20 @@ workflow:
         action: break
         condition: "{{may_repair}} == false"
 
+      # Only routed gaps left: no repair can change them, so do not ask for one.
+      - id: routed_only_break
+        action: break
+        condition: "{{plan_ok}} == true"
+
       - id: ask_repair
         action: ask
         prompt: |
           analyze-plan found spec↔plan gaps (spec.md is the anchor; domain-model.md is
           read-only here):
           {{analyze_gaps}}
+          {{plan_gap_count}} gap(s) have route `plan` — a repair rewrites the plan to close
+          them. Gaps with route `specify` are not repaired here; they are reported and
+          belong to /appweaver specify.
           Repair the drifting plan(s) to conform now, or report the gaps and stop?
         options: ["Repair", "Report and Skip"]
         answer_var: repair_choice
@@ -553,7 +607,8 @@ workflow:
         output_target: { type: file, path: "{{backend_plan}}" }
         task: |
           spec.md is the ANCHOR — update backend-plan.md (in context) to CONFORM to it,
-          closing the gaps whose lane is `backend` (the spec WINS every time):
+          closing the gaps whose lane is `backend` and whose route is `plan` (the spec WINS
+          every time). Leave `specify`-route gaps as the DA-n notes described below:
           {{analyze_gaps}}
           - Add a plan home for each uncovered spec FR/BR/CN/DC/IC/US/SC (a lifted
             CN-/DC-/IC- lands in a §1 domain invariant enforcement · the persistence
@@ -591,7 +646,9 @@ workflow:
         output_target: { type: file, path: "{{frontend_plan}}" }
         task: |
           spec.md is the ANCHOR — update frontend-plan.md (in context) to CONFORM to it,
-          closing the gaps whose lane is `frontend` (the spec WINS every time):
+          closing the gaps whose lane is `frontend` and whose route is `plan` (the spec WINS
+          every time). Leave each `specify`-route gap open, logged as a DA-n that routes to
+          /appweaver specify:
           {{analyze_gaps}}
           - Give every uncovered Experience Standard (UX-), user story and
             interaction-state FR- a home: a screen in the navigation section, a flow row,
@@ -618,52 +675,51 @@ workflow:
             already-conformant section VERBATIM.
           Return the COMPLETE updated frontend-plan.md content only.
 
-  # THE STOP IS MASTER MODE'S ALONE. Two independent raises, because the two reasons to
-  # pass are unrelated: the plans conform, or this run was never allowed to change them.
-  # A read-only run that found gaps has done its whole job by reporting them — stopping
-  # would fail the operator for drift that finalize-delta created on purpose and that only
-  # /appweaver plan main can close.
-  - id: gate_ok_conformant
-    condition: "{{analyze_ok}} == true"
-    action: set
-    vars: { gate_ok: "true" }
-  - id: gate_ok_readonly
-    condition: "{{may_repair}} == false"
-    action: set
-    vars: { gate_ok: "true" }
-
-  - id: analyze_gate
-    action: verify_context
-    require_true: gate_ok
-    on_false: stop
-    on_false_message: "The lane plans do not conform to the spec (gaps: {{analyze_gaps}}) — repair was skipped (see plan-analyze-report.md), or it could not be reconciled in 3 passes. A 'LIFT-FAILURE:' gap means a domain constraint from the gate checklist was never lifted into the spec, and a `model` gap means the plan needs an entity or invariant domain-model.md does not define — both are fixed by /appweaver specify, which authors the spec and the model; this gate may not write either. A `contract` gap is closed in the lane its row names. Otherwise fix out of band, or re-run and choose Repair."
-
   # THE RECEIPT. implement generates from the plans and deliberately does not read the
-  # spec, on the strength of this stage having conformed them to it — which until now was
-  # an assumption about the order the operator ran things in, checked by nothing. Record
-  # WHAT was proven: the bytes of spec.md, the context's domain-model.md and each lane plan
-  # that was present. plan-gate-check reads it at implement.
+  # spec, on the strength of this stage having checked them against it. Record WHAT was
+  # checked — the bytes of spec.md, the context's domain-model.md and each lane plan that
+  # was present — and the VERDICT on them. plan-gate-check reads it at implement.
   #
-  # ONLY A GREEN MASTER RUN LEAVES ONE. The AND is the kit's ordered assignment — under
-  # master mode, take the conformance verdict as the answer — because the engine has no
-  # compound conditions. A REPORT-mode run proves nothing about the masters (it may not
-  # even repair them), and a red master run proved the opposite.
+  # EVERY MASTER RUN LEAVES ONE, and it is written BEFORE the stop below, so a red run
+  # records its `gaps` verdict too and implement refuses it. A REPORT-mode run leaves
+  # none: it checked the masters while a delta was in flight, and they are about to move.
   - id: flag_receipt
     condition: "{{may_repair}} == true"
     action: set
-    vars: { stamp_receipt: "{{analyze_ok}}" }
+    vars: { stamp_receipt: "true" }
 
   - id: plan_gate_stamp
     condition: "{{stamp_receipt}} == true"
     action: execute_script
     script: { ref: actions }
     subcommand: plan-gate-stamp
-    args: ["--feature-dir", "{{feature_dir}}", "--spec-version", "{{version}}", "--mode", "{{gate_mode}}"]
+    args: ["--feature-dir", "{{feature_dir}}", "--spec-version", "{{version}}", "--mode", "{{gate_mode}}", "--verdict", "{{gate_verdict}}", "--plan-gaps", "{{plan_gap_count}}", "--routed", "{{routed_gaps}}"]
     outputs:
       - { name: receipt_file,  from: "$.file" }
       - { name: receipt_gated, from: "$.gated" }
       - { name: receipt_count, from: "$.count" }
 
+  # THE STOP IS MASTER MODE'S ALONE, and only a PLAN gap triggers it. Two independent
+  # raises, because the two reasons to pass are unrelated: no gap is left that a plan
+  # rewrite closes, or this run was never allowed to rewrite. A read-only run that found
+  # gaps has done its whole job by reporting them — stopping would fail the operator for
+  # drift that finalize-delta created on purpose and that only /appweaver plan main can
+  # close. Routed gaps pass here and are listed in the outputs for /appweaver specify.
+  - id: gate_ok_conformant
+    condition: "{{plan_ok}} == true"
+    action: set
+    vars: { gate_ok: "true" }
+  - id: gate_ok_readonly
+    condition: "{{may_repair}} == false"
+    action: set
+    vars: { gate_ok: "true" }
+
+  - id: analyze_gate
+    action: verify_context
+    require_true: gate_ok
+    on_false: stop
+    on_false_message: "The lane plans do not conform to the spec: {{plan_gap_count}} gap(s) a plan rewrite closes are still open (all gaps: {{analyze_gaps}}) — repair was skipped (see plan-analyze-report.md), or it did not converge in 3 passes. The receipt records verdict `gaps`, so /appweaver implement will refuse until this gate is re-run clean. A `contract` gap is closed in the lane its row names. Gaps routed to `specify` ({{routed_csv}}) are not what stopped this run: they need /appweaver specify, which authors the spec and the model. Fix out of band, or re-run and choose Repair."
+
   # (No change-close here by design — this stage never archives anything in either mode,
   #  and cr-archive belongs to close-delta, which runs after finalize-delta's merge.)
 
@@ -687,10 +743,13 @@ outputs:
   domain_model: "{{domain_model}}"
   conformant: "{{analyze_ok}}"
   gaps: "{{analyze_gaps}}"
+  verdict: "{{gate_verdict}}"       # conformant | routed-gaps | gaps
+  plan_gaps: "{{plan_gap_count}}"   # open gaps a plan rewrite closes
+  routed_to_specify: "{{routed_csv}}"   # open gaps only /appweaver specify can close
   version: "{{version}}"
   gate_mode: "{{gate_mode}}"        # master (repair allowed) | report (read-only)
   open_changes: "{{open_ids}}"      # empty in master mode, by definition
-  gate_receipt: "{{receipt_file}}"  # written only by a GREEN master run; implement reads it
+  gate_receipt: "{{receipt_file}}"  # written by every master run, with its verdict; implement reads it
   gate_receipt_at: "{{receipt_gated}}"
   note: "Ran in {{gate_mode}} mode ({{open_count}} change(s) open: {{open_ids}}). Checked: spec→backend-plan ({{be_present}}), spec→frontend-plan ({{fe_present}}), the plan↔plan contract binding ({{both_lanes}} — it needs both lanes) and both plans against domain-model.md. The domain model was READ, never written: a gap that needs a new entity, event or invariant is fixed by /appweaver specify. In REPORT mode no plan was rewritten either — the master plans are derived documents and may not move while a delta is in flight."
-  next: "MASTER mode (no change open, conformant={{analyze_ok}}): /appweaver implement — the plans conform to the spec; version unchanged, this gate closes nothing. REPORT mode (change(s) {{open_ids}} open): this run was read-only and wrote plan-analyze-report.md only. If finalize-delta has already merged, the gaps ARE that merge — the lane plans are derived from spec.md + domain-model.md and finalize-delta moves only those two, so re-derive with /appweaver plan main after /appweaver close-delta, then re-run /appweaver analyze-plan in master mode. If the change has NOT merged yet, gate it where it lives: /appweaver analyze-plan-delta."
+  next: "MASTER mode (no change open, verdict={{gate_verdict}}): /appweaver implement — no gap a plan rewrite closes is left; version unchanged, this gate closes nothing. If the verdict is routed-gaps, implement generates and warns: {{routed_csv}} — each is a spec or model gap, lifted by opening a change with /appweaver specify. REPORT mode (change(s) {{open_ids}} open): this run was read-only and wrote plan-analyze-report.md only. If finalize-delta has already merged, the gaps ARE that merge — the lane plans are derived from spec.md + domain-model.md and finalize-delta moves only those two, so re-derive with /appweaver plan main after /appweaver close-delta, then re-run /appweaver analyze-plan in master mode. If the change has NOT merged yet, gate it where it lives: /appweaver analyze-plan-delta."

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

@@ -70,7 +70,7 @@
 # =============================================================================
 
 name: aw-spec-analyze-slice-delta
-version: 1.0.0
+version: 1.1.0
 description: "The delta-spec↔delta-code gate — verify that the open change DOES WHAT IT WAS ASKED TO DO, before it reaches the master documents. delta-spec.md is the anchor, exactly as it is for analyze-plan-delta. Asks which open change it is gating, runs the slice's tests (the first execution on the change path, since build only compiles), then evaluates the code and its paired tests against the change's REQUIREMENTS — every ADDED or MODIFIED delta-spec item realised in code, every one covered by a test that cites its id, every invariant the model delta adds actually enforced — with the delta plan in context as the map from requirement to code and cross-checked in its own right, so an element the plan promised and nobody built is caught too. The dynamic twin of analyze-plan-delta and the delta twin of analyze-slice, which cannot see a missing implementation because a behaviour that was never built leaves no failing test. Verify-only — it reports each finding with the command that closes it and stops; it generates no code and repairs nothing."
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
@@ -124,6 +124,7 @@ vars:
   test_ok: "false"
   test_tool: ""
   test_log: ""
+  test_excerpt: ""
   test_scoped: "false"
   test_ran: "false"
   test_matched: "false"
@@ -155,9 +156,11 @@ workflow:
       - { name: be_declared,    from: "$.backend_declared" }
       - { name: be_lane_id,     from: "$.backend_lane_id" }
       - { name: be_source_path, from: "$.backend_source_path" }
+      - { name: be_test_path,   from: "$.backend_test_path" }
       - { name: fe_declared,    from: "$.frontend_declared" }
       - { name: fe_lane_id,     from: "$.frontend_lane_id" }
       - { name: fe_source_path, from: "$.frontend_source_path" }
+      - { name: fe_test_path,   from: "$.frontend_test_path" }
 
   - id: require_lane
     action: verify_context
@@ -316,6 +319,7 @@ workflow:
       - { name: test_ok,      from: "$.fence_green" }
       - { name: test_tool,    from: "$.tool" }
       - { name: test_log,     from: "$.log_tail" }
+      - { name: test_excerpt, from: "$.failing_excerpt" }   # the lines that NAME the failure
       - { name: test_scoped,  from: "$.scoped" }
       # A GREEN FENCE IS NOT ALWAYS AN EXECUTED SUITE. test-run reports fence_green true
       # with ran=false on a project whose lanes declare no test command — the vacuous pass
@@ -414,9 +418,11 @@ workflow:
       the pre-existing slice.
 
       CHECK 7 — PLACEMENT. Every file this change added or edited sits under the lane that
-      owns it: this lane's source path is `{{be_source_path}}`. A service-lane element
-      written into the frontend lane's subtree — or outside every lane root — is a HIGH
-      `placement` gap.
+      owns it: this lane's production code under its source path `{{be_source_path}}`, its
+      tests under its test path `{{be_test_path}}`. A service-lane element written into the
+      frontend lane's subtree — or outside every lane's paths — is a HIGH `placement` gap.
+      One edit outside them is allowed: registering a test project this change created in
+      the file the lane's test command discovers tests through (e.g. a .NET solution file).
 
       PLAN-ONLY CHANGE — if the delta-spec is an unfilled stub, this change deliberately
       alters only HOW the EXISTING spec is realised (a refactor, an architectural decision).
@@ -506,9 +512,11 @@ workflow:
       gap. Judge it only over what this change touched.
 
       CHECK 7 — PLACEMENT. Every file this change added or edited sits under this lane's
-      source path, `{{fe_source_path}}`. A file written into the service lane's subtree is a
-      HIGH `placement` gap — a gap in the service surface is a contract delta raised back to
-      that lane, never a client-side edit to it.
+      source path, `{{fe_source_path}}`, or — for a test — its test path, `{{fe_test_path}}`.
+      A file written into the service lane's subtree is a HIGH `placement` gap — a gap in the
+      service surface is a contract delta raised back to that lane, never a client-side edit
+      to it. The one edit allowed outside them is the test setup this change had to create,
+      when the lane's test command discovers tests through a file elsewhere.
 
       PLAN-ONLY CHANGE — if the delta-spec is an unfilled stub, this change alters only HOW
       the existing spec is realised. Checks 1 to 3 have no anchor and are SKIPPED, not
@@ -568,8 +576,8 @@ workflow:
       merges the change into spec.md and domain-model.md.
       Evidence:
       - tests: green={{test_ok}}, tool `{{test_tool}}`, actually ran={{test_ran}},
-        matched a slice filter={{test_matched}}, slice-scoped={{test_scoped}}. Log tail:
-        {{test_log}}
+        matched a slice filter={{test_matched}}, slice-scoped={{test_scoped}}. Failing
+        lines: {{test_excerpt}} · Log tail: {{test_log}}
       - service lane gated={{be_gated}}, verdict ok={{be_ok}}, gaps: {{be_gaps}}
       - experience lane gated={{fe_gated}}, verdict ok={{fe_ok}}, gaps: {{fe_gaps}}
       Markdown format: