aw-spec-cli 0.1.21 → 0.1.23

package/assets/.appweaver/STACK-PROFILES.md

@@ -51,15 +51,17 @@ no heading to key on. Where the two lanes are folded into one command, as `plan`
 | `stack` | *(optional)* what the code was found to be, when `profile` is `detected` — e.g. `asp.net-webforms`. The honest record for a legacy lane |
 | `origin` | *(optional)* `reverse-engineered` on a lane `onboard` derived from an existing codebase. Absent means a person declared it, which is the greenfield shape and the historical one |
 | `root` | the lane's **source path** — the subtree it owns (see §3). `--source-path` and `--root` are two spellings of this one field |
+| `test_root` | *(optional)* the lane's **test path**, written by hand only when the profile's answer does not fit this layout. Absent, `lane-resolve` / `lane-verify` work it out from the profile at read time (§4.3), so no lane has to be re-declared for it |
 | `run_from` | *(optional)* **where the commands run**: `repo` (the default, and the shape of every lane written before this key existed) at the repository root, or `root` inside the lane's own source path. See §3.1 |
 | `build` / `test` / `run` | project-supplied command strings the engine shells out to. These are the matched **profile's** defaults and may not fit a legacy layout — reviewing them is what `select-stack` is for. `{{root}}` in a command resolves to this lane's `root` (§4.2) |
 | `migrate` | *(optional)* the lane's schema-migration command, recorded only when the profile declares one. Absent, `run-migrate` falls back to `dotnet ef` and otherwise reports that nothing ran (§4.2) |
 
 ### Three properties matter more than the schema
 
-1. **`root` is ownership, and it is the source path.** `implement`'s service lane writes only
-   under a backend lane's root and its frontend lane only under a frontend lane's,
-   `build`/`test`/`run` act on it, and `onboard` reverse-engineers out of it.
+1. **`root` is ownership, and it is the source path.** `implement`'s service lane writes its
+   code only under a backend lane's root and its frontend lane only under a frontend lane's,
+   `build`/`test`/`run` act on it, and `onboard` reverse-engineers out of it. The lane's
+   **test path** (§4.3) is owned the same way, and is where `implement` writes the lane's tests.
 2. **The commands are project-supplied strings.** The engine stays stdlib-only and
    stack-ignorant. This is how `build` already avoids knowing what a compiler is, and it
    is the only thing that makes "any frontend stack" tractable.
@@ -151,12 +153,17 @@ Declaring **`(none)`** for a lane is a real answer and the way a project says it
 ## 3. The ownership rule
 
 **Lane roots own their subtree and must be disjoint.** Two generators must never be able
-to write the same file.
+to write the same file. A lane owns its test path too, so the rule covers both: no source or
+test path of one lane may overlap a source or test path of another.
 
-`lane-declare` refuses a declaration whose root contains, or is contained by, another
+`lane-declare` refuses a declaration whose paths contain, or are contained by, another
 lane's — compared as `/`-terminated paths, so `src/` is clear of `src-gen/` but collides
 with `src/api/`. The refusal is a non-zero exit and **`stacks.json` is left untouched**.
 
+The one write `implement` may make outside a lane's two paths is registering a test project
+it had to create, in the file the lane's test command discovers tests through — the solution
+file for .NET. `analyze-slice-delta`'s placement check accepts that edit and nothing else.
+
 This is checked at declaration time on purpose. The alternative — discovering it when two
 implement phases fight over a file — is a much worse place to find out.
 
@@ -176,12 +183,15 @@ workflow.**
   "language": "TypeScript",                  // shown in the menu, parenthesised
   "ecosystem": "node",                       // which stack-partitioned corpus this stack draws from
   "root": "web/",                            // the lane root this profile defaults to
+  "test_root": "",                           // optional — where tests go when not inside root — see §4.3
   "run_from": "root",                        // where the commands run — see §3.1
   "build": "npm run build",
   "test":  "npm test",
   "run":   "npm run dev",
   "migrate": "",                             // optional — schema migration, if the stack has one
   "prototype_run": "npm run dev --prefix prototype",   // frontend only — fills the prototype block
+  "reserved_names": ["Event", "Request", "Response"],  // optional — names this stack's AMBIENT
+                                             // scope already defines; see §4.4
   "detect": ["web/package.json", "web/vite.config.*"]  // ANY-of markers — how stack-detect recognises this stack
 }
 ```
@@ -206,10 +216,23 @@ trees that are physically per-ecosystem:
 compiling project and a component runbook edits a host project's build files — both are
 executable artifacts in one toolchain, so offering a `dotnet` bundle to a Spring repo does not
 produce a scaffold, it produces a second foreign project beside the real one. `foundation-list`
-therefore narrows to the declared lanes' ecosystems, and reports `all_foundations` alongside so
-the gate can say *what exists and why none of it applies*. A repo that has declared nothing yet
+therefore narrows by ecosystem, and reports `all_foundations` alongside so the gate can say
+*what exists and why none of it applies*. `--ecosystem` narrows to the ONE lane being
+scaffolded, which is what `foundation` passes: a repo declaring a .NET service and a Node UI
+must not be offered its .NET bundle while the UI lane is the target. Without that argument the
+filter falls back to every declared lane's ecosystem, and a repo that has declared nothing yet
 is not filtered — there is no answer to filter on.
 
+**A scaffold lands in a lane.** `foundation` unpacks a bundle into the SOURCE PATH of the lane
+it is scaffolding — never the repository root, and there is no output-directory argument. One
+bundle fills one lane, so a fullstack repo runs `foundation` once per lane. This is what makes
+every phase's "write only into your lane" rule true of the scaffold as well as of generated
+code: `implement`, `build`, `test` and `run` all resolve the same path the bundle unpacked into.
+A pack carrying its own test tree has it lifted onto the lane's **test path** (§4.3) afterwards,
+because for most backend stacks that path is a sibling of the source path rather than a
+directory inside it. Lanes must therefore be declared before `foundation` runs, which is why
+`select-stack` is the first command of both sequences.
+
 The technical RULE corpora at `guardrails/technology/<stack>/` are keyed by **profile id**, not
 ecosystem, because Spring and Quarkus are both `java` and do not share a persistence rule. They
 are selected through the project's `tech-rule-bindings.md` rather than filtered here — see §7.
@@ -274,6 +297,61 @@ about a backend, and the two errors are not symmetric. A false positive authors
 the project never asked for; a false negative only produces a warning that names the fix. Pick
 ids accordingly — a profile whose id is a common English word will be matched too eagerly.
 
+### 4.4 `reserved_names` — names the stack already defines
+
+A stack's ambient scope defines types nobody imported: C#'s implicit usings put `System`,
+`System.Threading.Tasks`, `Microsoft.AspNetCore.Http` and `Microsoft.AspNetCore.Routing` in
+every file of a `Microsoft.NET.Sdk.Web` project; a browser bundle has `Event`, `Request` and
+`Response`; `java.lang` is always imported; `typing` is star-imported by convention.
+
+A domain noun that matches one of those is **not a naming mistake** — `Route`, `Task`,
+`Order` and `Activity` are ordinary domain vocabulary, the plan carries the ubiquitous
+language, and the generator spells it verbatim. But written bare it is ambiguous, and in C#
+it does not compile (CS0104). The conflict is invisible in the file: the framework name
+arrives through an implicit import and appears in no line of it.
+
+`reserved_names` lists the ones that are BOTH ambient on this stack AND plausible domain
+vocabulary — curated, not an exhaustive dump of the standard library. `lane-resolve` and
+`lane-verify` report it as `<kind>_reserved_names` / `<kind>_reserved_csv`; `implement`
+passes it to `plan-coverage --reserved`, which intersects it with the plan's own element
+names and hands the generating lane the actual collisions before it writes anything. The
+per-stack resolution convention is in that stack's rule corpus — for `dotnet-webapi`, in
+[[framework-api-map]]: qualify with the enclosing namespace segment (`Domain.Route`), never
+rename the domain type.
+
+Absent, nothing is reported and generation is unchanged.
+
+### 4.3 `test_root` — where a lane's tests go
+
+Most backend stacks keep their tests **beside** the source, not inside it: .NET's `tests/` next
+to `src/`, Maven's `src/test/java/` next to `src/main/java/`, pytest's `tests/` next to `app/`.
+A lane that owned only its source path could not hold its own tests, so each lane also owns a
+**test path**, and `implement` writes the lane's paired tests there.
+
+A profile's `test_root` is the test path that pairs with its default `root`. `lane-resolve` and
+`lane-verify` report it per kind as `backend_test_path` / `frontend_test_path`, worked out at
+read time:
+
+| The lane | Its test path |
+|---|---|
+| declares `test_root` itself | that value |
+| sits at the profile's default root (`src/`) | the profile's `test_root` (`tests/`) |
+| sits at a path ending in the default root (`backend/src/`) | the profile's `test_root` under the same prefix (`backend/tests/`) |
+| anything else, or the profile declares no `test_root` | the source path itself |
+
+The last row is right for every shipped frontend (tests under `web/tests/`), for Go's
+colocated `_test.go` files, and for a Maven lane rooted at the directory holding its
+`pom.xml`, where `src/test/java/` is already inside the lane. A layout the table gets wrong is
+fixed by writing `test_root` on the lane in `stacks.json`.
+
+| Profile | `root` | `test_root` |
+|---|---|---|
+| `dotnet-webapi` | `src/` | `tests/` |
+| `java-spring` | `src/main/java/` | `src/test/java/` |
+| `python-fastapi` | `app/` | `tests/` |
+| `node-express` | `src/` | `tests/` |
+| `go-chi` and every frontend | — | *(none — inside the source path)* |
+
 ---
 
 ## 5. Who may write this file
@@ -398,7 +476,8 @@ set**, so a caller binds outputs without knowing which branch ran.
 | `test-run` | every declared lane's own `test`, via `run-phase` — **except** `--scope slice` on a repo where a .NET toolchain is present, which keeps the VSTest `--filter` path | the historic ladder |
 | `run-migrate` | a lane's declared `migrate` (§4.2) when there is one; otherwise `dotnet ef` searched under the **service lane's root** rather than an assumed `src/` | `dotnet ef` under `src/` |
 | `find-host-project` | searches the service lane's root, and reports the lane's `ecosystem` | searches `src/` |
-| `foundation-list`, `list-components` | narrowed to the declared lanes' `ecosystem` (§4.1) | unfiltered / `dotnet` |
+| `foundation-list`, `list-components` | narrowed to the `ecosystem` of the lane being scaffolded, else of every declared lane (§4.1) | unfiltered / `dotnet` |
+| `foundation-unpack` | unpacks into the lane's **source path**, and lifts a packed test tree onto its **test path** (§4.1, §4.3) | cannot run — `foundation` stops until a lane is declared |
 | `resolve-tech` | expands stack placeholders and flags a corpus mismatch (§7a) | no placeholders resolve; nothing is flagged |
 
 **Why `--scope slice` is the one exception.** VSTest's `--filter FullyQualifiedName~` is the

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

@@ -130,6 +130,14 @@ workflow:
                                              # the context's CANONICAL model — the aggregate root,
                                              # its entities and its invariants live here, not in the
                                              # spec and not in this plan.
+      - { path: "{{cr_dir}}/delta-slice-analyze-report.md", optional: true }
+                                             # WHAT THE LAST GATE FOUND, when this change
+                                             # has already been through analyze-slice-delta.
+                                             # A `plan` finding there says THIS document is
+                                             # what was wrong, and re-deriving it is how that
+                                             # finding is closed — the alternative is hand-
+                                             # editing a generated plan, which every
+                                             # authoring rule forbids. Absent on a first pass.
       - { path: .appweaver/DESIGN-FORMAT.md }
   - id: author_backend_delta
     condition: "{{be_existing}} == true"
@@ -148,6 +156,13 @@ workflow:
         IS, and a delta that ignores the difference plans an edit to something that is not
         there. Where the two disagree, plan against the code and record the divergence as
         a WA-n.
+      - THE LAST GATE'S REPORT, when one is in context (delta-slice-analyze-report.md).
+        It records what analyze-slice-delta found the last time this change was gated. A
+        finding tagged `fix: plan` says THIS document was what was wrong — re-derive the
+        rows it names, against the code it names. EVIDENCE, never a requirement source: the
+        delta-spec stays the only authority on what the change must do, and a finding
+        tagged `implement` or `specify` is closed elsewhere and is not this pass's work.
+        Absent on a first pass, which is the normal case.
       - Classify every change to the plan as ADDED / MODIFIED / REMOVED against the
         master, per the master's OWN section structure (whatever sections it actually has
         — do not assume a fixed layering), plus the cross-section impact, the regression
@@ -231,6 +246,14 @@ workflow:
                                              # frontend-only project has no service lane at all.
       - { path: "{{domain_model}}", optional: true }
       - { path: .appweaver/memory/constitution.ui.md, optional: true }
+      - { path: "{{cr_dir}}/delta-slice-analyze-report.md", optional: true }
+                                             # WHAT THE LAST GATE FOUND, when this change
+                                             # has already been through analyze-slice-delta.
+                                             # A `plan` finding there says THIS document is
+                                             # what was wrong, and re-deriving it is how that
+                                             # finding is closed — the alternative is hand-
+                                             # editing a generated plan, which every
+                                             # authoring rule forbids. Absent on a first pass.
       - { path: .appweaver/DESIGN-FORMAT.md }
   - id: author_frontend_delta
     condition: "{{fe_existing}} == true"
@@ -247,6 +270,13 @@ workflow:
         feature: {{source_files}}. Read the ones this change touches — a delta that plans
         an edit to a component that is not there, or that duplicates one that is, costs a
         whole implementation pass to discover.
+      - THE LAST GATE'S REPORT, when one is in context (delta-slice-analyze-report.md).
+        It records what analyze-slice-delta found the last time this change was gated. A
+        finding tagged `fix: plan` says THIS document was what was wrong — re-derive the
+        rows it names, against the code it names. EVIDENCE, never a requirement source: the
+        delta-spec stays the only authority on what the change must do, and a finding
+        tagged `implement` or `specify` is closed elsewhere and is not this pass's work.
+        Absent on a first pass, which is the normal case.
       - Classify every change ADDED / MODIFIED / REMOVED against the master, per the
         master's OWN sections. A shared component or a shared state container is MODIFIED
         in place, never copied into the change.

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

@@ -101,6 +101,7 @@ Execution strategies (--strategy, overridable per step via `strategy:`):
   suspend/resume.
 """
 import argparse
+import glob
 import importlib.util
 import json
 import os
@@ -1491,7 +1492,7 @@ def _module_script_refs(mpath, base_dir, seen):
     return out
 
 
-def validate_workflow(wf, base_dir):
+def validate_workflow(wf, base_dir, path=""):
     errors, warnings = [], []
     if not isinstance(wf, dict):
         return (["top-level YAML is not a mapping"], [])
@@ -1621,9 +1622,51 @@ def validate_workflow(wf, base_dir):
     for name in sorted(used):
         if name.split(".")[0] not in produced:
             warnings.append(f"variable {{{{{name}}}}} referenced but never produced")
+    errors_n, warnings_n = _validate_next(wf, base_dir, path)
+    return errors + errors_n, warnings + warnings_n
+
+
+# outputs.next is the ONLY channel a finished run has for telling the operator what
+# to run next: the engine returns wf["outputs"] and the launching agent relays it.
+# Both faults it guards are silent — a next: indented out of the outputs map is
+# parsed and dropped, and a retired command name still reads as a valid sentence —
+# so the run ends looking successful and the agent invents a successor to fill the
+# gap. Warnings, not errors: a workflow may legitimately name a command that is
+# designed but not yet built, and pre-flight refuses to start on errors alone.
+def _validate_next(wf, base_dir, path=""):
+    errors, warnings = [], []
+    outputs = wf.get("outputs") or {}
+    known = {os.path.basename(p)[len("aw-spec-"):-len(".orch.yaml")]
+             for p in glob.glob(os.path.join(base_dir, "aw-spec-*.orch.yaml"))}
+    # A module has no successor to name: it is included INTO a caller, and the caller's
+    # own next covers the run. Only a launchable aw-spec-<name> workflow is asked for one.
+    launchable = os.path.basename(path).startswith("aw-spec-") if path else bool(known)
+    if launchable and "next" not in outputs:
+        where = " (it is at the document's top level, OUTSIDE outputs:, so the " \
+                "engine parses it and then drops it)" if "next" in wf else ""
+        warnings.append(f"outputs: declares no 'next' — the run ends with no "
+                        f"suggested successor{where}")
+    if not known:          # validating a module, or a workflow read from elsewhere
+        return errors, warnings
+    for text in _output_strings(outputs):
+        for cmd in re.findall(r"/appweaver\s+([a-z][a-z0-9-]*)", text):
+            if cmd not in known:
+                warnings.append(f"outputs names '/appweaver {cmd}', which resolves "
+                                f"to no aw-spec-{cmd}.orch.yaml")
     return errors, warnings
 
 
+def _output_strings(v):
+    if isinstance(v, str):
+        yield v
+    elif isinstance(v, list):
+        for x in v:
+            yield from _output_strings(x)
+    elif isinstance(v, dict):
+        for x in v.values():
+            yield from _output_strings(x)
+
+
 def _print_suspended(pending, opts):
     """Checkpoint transport: hand the pending request to the INVOKING agent."""
     if opts.json:
@@ -1710,7 +1753,7 @@ def main(argv=None):
                   if opts.json else f"ERROR: parse: {e}")
             return 1
         errors, warnings = validate_workflow(
-            wf, os.path.dirname(os.path.abspath(opts.workflow)))
+            wf, os.path.dirname(os.path.abspath(opts.workflow)), opts.workflow)
         if opts.json:
             print(json.dumps({"status": "valid" if not errors else "invalid",
                               "errors": errors, "warnings": warnings}, indent=2))
@@ -1732,7 +1775,8 @@ def main(argv=None):
     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)))
+        errors, _ = validate_workflow(
+            wf, os.path.dirname(os.path.abspath(opts.workflow)), opts.workflow)
     except Exception as e:
         wf, errors = None, [f"parse: {e}"]
     if errors:

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

@@ -105,6 +105,7 @@ vars:
   may_repair: "false"      # the ask, the repair loop and the conformance stop are MASTER-only
   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
+  repairs_left: "true"     # lowered on the loop's final pass, which checks and never rewrites
   # 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
@@ -383,13 +384,23 @@ workflow:
 
   # 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.
+  #    and stops. 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.
+  #
+  #    THREE REPAIRS, FOUR PASSES — the last pass checks and never rewrites. With the two
+  #    equal, the third repair was the last thing to run: no pass ever saw its result, so a
+  #    run that converged on it still reported `gaps` and told the operator it had not
+  #    converged. Worse, plan_ok / gate_verdict / plan_gap_count then described the plans as
+  #    they were BEFORE that repair, while plan-gate-stamp below hashed the files as they
+  #    are AFTER it — a receipt pairing post-repair bytes with a pre-repair verdict, which
+  #    plan-gate-check would later read as fresh. The extra pass costs one analyze in the
+  #    case that used to end ambiguously, and it makes the last thing to touch the plans
+  #    always earlier than the last thing to judge them, on every exit path.
   - id: analyze_loop
     action: loop
     while: "{{plan_ok}} != true"
-    max_iterations: 3
+    max_iterations: 4
     steps:
       - id: analyze
         action: agent_query
@@ -546,7 +557,19 @@ workflow:
         action: break
         condition: "{{plan_ok}} == true"
 
+      # THE LAST PASS CONFIRMS THE LAST REPAIR AND DOES NOT ADD ONE. Raised for every pass
+      # and lowered on the final one, so the ask below and both lane rewrites are skipped
+      # there while the analyze above still runs and still sets the verdict.
+      - id: repairs_left_yes
+        action: set
+        vars: { repairs_left: "true" }
+      - id: repairs_left_no
+        condition: "{{iteration}} == 3"
+        action: set
+        vars: { repairs_left: "false" }
+
       - id: ask_repair
+        condition: "{{repairs_left}} == true"
         action: ask
         prompt: |
           analyze-plan found spec↔plan gaps (spec.md is the anchor; domain-model.md is
@@ -582,9 +605,11 @@ workflow:
         condition: "{{repair_choice}} == Report and Skip"
 
       # WHICH DOCUMENT GETS REWRITTEN. A repair runs only where the analyze pass reported
-      # drift in that lane AND that lane is present — two ordered assignments per lane,
-      # cleared first so a lane that was repaired on the previous iteration and is clean
-      # on this one is not rewritten again.
+      # drift in that lane AND that lane is present AND this pass still carries a repair —
+      # three ordered assignments per lane, because the dialect takes no compound
+      # condition. Cleared first so a lane that was repaired on the previous iteration and
+      # is clean on this one is not rewritten again, and cleared last on the final pass,
+      # which exists to check the previous repair rather than to add another.
       - id: be_repair_clear
         action: set
         vars: { be_repair: "false" }
@@ -592,6 +617,10 @@ workflow:
         condition: "{{backend_repair}} == true"
         action: set
         vars: { be_repair: "{{be_present}}" }
+      - id: be_repair_last_pass
+        condition: "{{repairs_left}} == false"
+        action: set
+        vars: { be_repair: "false" }
       - id: fe_repair_clear
         action: set
         vars: { fe_repair: "false" }
@@ -599,6 +628,10 @@ workflow:
         condition: "{{frontend_repair}} == true"
         action: set
         vars: { fe_repair: "{{fe_present}}" }
+      - id: fe_repair_last_pass
+        condition: "{{repairs_left}} == false"
+        action: set
+        vars: { fe_repair: "false" }
 
       - id: repair_backend
         condition: "{{be_repair}} == true"
@@ -718,7 +751,7 @@ workflow:
     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."
+    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}}). Either you chose `Report and Skip`, in which case plan-analyze-report.md beside the plans lists them — or repair ran up to three times and the fourth pass, which checks and does not rewrite, still found these. Every gap above was read off the plans as they stand on disk now. 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.)

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

@@ -70,7 +70,7 @@
 # =============================================================================
 
 name: aw-spec-analyze-slice-delta
-version: 1.1.0
+version: 1.2.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
@@ -130,6 +130,18 @@ vars:
   test_matched: "false"
   # Verdict.
   requirements_ok: "false"
+  # Findings split by the command that closes them (gap-route). Defaults read as
+  # "nothing found", so a run where the router could not execute still prints.
+  gap_summary: "no findings"
+  gap_total: "0"
+  fix_code: "none"
+  fix_code_n: "0"
+  fix_plan: "none"
+  fix_plan_n: "0"
+  fix_spec: "none"
+  fix_spec_n: "0"
+  fix_review: "none"
+  fix_review_n: "0"
   gate_ok: "false"
 
 workflow:
@@ -547,6 +559,30 @@ workflow:
     action: set
     vars: { requirements_ok: "false" }
 
+  # WHO CAN CLOSE WHAT. Both lanes' findings carry a `fix` tag already; this turns the tag
+  # into routing. It matters most for a `plan` finding: the delta plan is what is wrong, and
+  # `implement` generates FROM that plan, so sending it there reproduces the defect — which
+  # is what left the mock run's ChiefComplaintField gap closable only by hand-editing a
+  # generated plan. Deterministic, and it never drops a finding: one with no recognised
+  # `fix` is routed to `review` and counted, rather than folded into the largest bucket.
+  - id: route_gaps
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: gap-route
+    args: ["--cr", "{{cr_id}}", "--gaps", "{{be_gaps}}", "--gaps", "{{fe_gaps}}"]
+    outputs:
+      - { name: gap_summary,   from: "$.summary" }
+      - { name: gap_total,     from: "$.total" }
+      - { name: fix_code,      from: "$.implement_text" }
+      - { name: fix_code_n,    from: "$.implement_count" }
+      - { name: fix_plan,      from: "$.plan_text" }
+      - { name: fix_plan_n,    from: "$.plan_count" }
+      - { name: fix_spec,      from: "$.specify_text" }
+      - { name: fix_spec_n,    from: "$.specify_count" }
+      - { name: fix_review,    from: "$.review_text" }
+      - { name: fix_review_n,  from: "$.review_count" }
+
   # gate_ok = the tests ran green AND every gated lane's requirements are met.
   - id: gate_flag
     condition: "{{test_ok}} == true"
@@ -616,7 +652,31 @@ workflow:
     action: verify_context
     require_true: gate_ok
     on_false: stop
-    on_false_message: "Change {{cr_id}} does NOT yet meet its delta spec. Tests green={{test_ok}} (tool `{{test_tool}}`); service lane gated={{be_gated}} ok={{be_ok}}; experience lane gated={{fe_gated}} ok={{fe_ok}}. Findings — backend: {{be_gaps}} · frontend: {{fe_gaps}}. The full report, with the command that closes each finding, is at {{cr_dir}}/delta-slice-analyze-report.md. DO NOT run finalize-delta yet: merging now would write requirements into spec.md and domain-model.md that the code does not satisfy, and the masters would describe an intention rather than the system. Fix the findings (a `requirement` or `plan` finding is usually /appweaver implement {{cr_id}}), re-run build, then re-run this gate."
+    on_false_message: >
+      Change {{cr_id}} does NOT yet meet its delta spec. Tests green={{test_ok}} (tool
+      `{{test_tool}}`); service lane gated={{be_gated}} ok={{be_ok}}; experience lane
+      gated={{fe_gated}} ok={{fe_ok}}. {{gap_summary}}
+
+      EACH FINDING IS CLOSED BY A DIFFERENT COMMAND — they are not interchangeable, and a
+      plan defect sent to implement comes back unchanged, because implement generates FROM
+      the plan.
+
+      SPEC / MODEL ({{fix_spec_n}}): {{fix_spec}}
+
+      DELTA PLAN ({{fix_plan_n}}): {{fix_plan}}
+
+      CODE ({{fix_code_n}}): {{fix_code}}
+
+      UNROUTED ({{fix_review_n}}): {{fix_review}}
+
+      Work them in that order — the spec before the plan that realises it, the plan before
+      the code that maps to it. Re-running /appweaver plan {{cr_id}} re-derives the delta
+      plans with this report in context, so a plan finding is fixed by re-deriving rather
+      than by hand-editing a generated document. The full report is at
+      {{cr_dir}}/delta-slice-analyze-report.md. DO NOT run finalize-delta yet: merging now
+      would write requirements into spec.md and domain-model.md that the code does not
+      satisfy, and the masters would describe an intention rather than the system. Then
+      re-run build and re-run this gate.
 
   # 6. Post-execution hooks.
   - id: resolve_post_hooks

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

@@ -136,9 +136,11 @@ vars:
   # Integrity pass (referrer blast radius) defaults — safe values if xref/test-run is
   # skipped or errors, so the gate reads a real verdict rather than an empty var.
   integrity_ok: "false"
-  referrer_csv: ""
+  referrer_csv: ""          # referrers THAT HAVE CODE — what the fence can actually run
   referrer_count: "0"
   referrer_names: ""
+  unbuilt_referrers: ""     # referrers that are planned and not implemented: nothing to run
+  unbuilt_count: "0"
   # Pass-3 (OKF) reporting defaults — the knowledge pass is advisory, so these stay
   # readable in the outputs even when a step is skipped or errors out.
   okf_ok: "unknown"
@@ -617,6 +619,12 @@ workflow:
   # broken referrer STOPS the gate for a human to resolve, it is not auto-fixed here.
   # Empty referrer set (a leaf feature, or the only aggregate in the repo) → the fence is just
   # the feature's own tests again → passes trivially, blocks nothing.
+  #
+  # THE FENCE TAKES THE BUILT HALF OF THE CLOSURE. Edges are read off the lane PLAN, so a
+  # referrer can be fully planned and hold no code: running its tests means running none,
+  # and this fence would report that emptiness as a result. An unbuilt referrer is still
+  # counted and named — it refers to this aggregate and has never been exercised against
+  # it, which is a different statement from passing.
   - id: xref_referrers
     action: execute_script
     on_error: continue
@@ -624,9 +632,11 @@ workflow:
     subcommand: list
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: referrer_csv,   from: "$.referrer_closure_csv" }
-      - { name: referrer_count, from: "$.referrer_closure_count" }
-      - { name: referrer_names, from: "$.referrer_closure" }
+      - { name: referrer_csv,     from: "$.built_closure_csv" }
+      - { name: referrer_count,   from: "$.built_count" }
+      - { name: referrer_names,   from: "$.built_closure" }
+      - { name: unbuilt_referrers, from: "$.unbuilt_closure_csv" }
+      - { name: unbuilt_count,     from: "$.unbuilt_count" }
 
   # Skipped when PASS 1 found nothing to run: this is the same test command over a wider
   # scope, so with no tests it would report the same emptiness a second time and fail a
@@ -675,7 +685,10 @@ workflow:
       REFER to this feature whose tests went red when this feature's change was run
       against them. This is a triage record for a human — analyze-slice does NOT fix a
       referrer (that is the referrer's own slice's job). Referrer blast radius
-      ({{referrer_count}}): {{referrer_names}}. Failing test log:
+      ({{referrer_count}}): {{referrer_names}}. Also referring to this aggregate but NOT
+      YET BUILT ({{unbuilt_count}}): {{unbuilt_referrers}} — planned, holding no code, so
+      the fence ran nothing for them; say plainly that they were not exercised rather than
+      leaving them out of the report. Failing test log:
       {{integrity_log}}
       Write markdown, in this order:
       - `# Broken Referrers — <feature>` and a one-line statement of what this file is:

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

@@ -724,4 +724,4 @@ outputs:
   ui_validation_ok: "{{ui_ok}}"
   ui_validation_issues: "{{ui_issues}}"
   note: "Split constitution authored, one half per LANE the project declared in .appweaver/stacks.json. service_lane / ui_lane report which lanes were found there, and the declaration is the ONLY signal read: a half is a lane's standing governance, so a lane declared `(none)` in select-stack gets no half AND no file. constitution.technical.md is the service lane's base (standing input to the SERVICE lane of plan + implement); constitution.ui.md is the UI lane's UX-* base (standing input to their FRONTEND lane); constitution.domain.md is the domain addenda (standing input to specify + a gate checklist), and it is always authored because domain is not a lane — it addends whichever halves exist. All are composed into constitution.md, which now tolerates an absent technical half: a UI-only project's domain half opens the roman-numeral sequence at I instead of continuing one, and numbering_checked reports false because that check has no subject rather than because it silently passed. Mapping ## /aw-spec-ui-constitution supplies the rules the UI half ratifies but no longer creates the lane on its own — a mapped rule set with no declared lane produces a warning naming both fixes. ui_lane false with ui_included true means a lane was retired after its half was authored: the file is left alone and the log says so, because a ratified governance file is never deleted automatically. If a validation_ok is false, the matching validation_issues lists what still needs a manual touch. See each half's Sync Impact Report for its version bump. Suggested commit: 'docs: amend split constitution'."
-  next: "Loaded per concern — /appweaver specify loads constitution.domain.md; the SERVICE lane of plan + implement loads constitution.technical.md; their FRONTEND lane loads constitution.ui.md. Re-run /appweaver constitution to amend, including to pick up a lane declared or dropped after this run — re-run /appweaver select-stack first to change which lanes exist."
+  next: "/appweaver select-feature → specify. select-feature picks the feature to build and every stage from specify onward reads that active feature and stops without it; on a brownfield workspace pick the bounded context first with /appweaver select-bounded-context. From specify the greenfield sequence runs plan → analyze-plan → implement → build → analyze-slice → run → deploy. THE HALVES ARE LOADED PER CONCERN, not all at once — /appweaver specify loads constitution.domain.md; the SERVICE lane of plan + implement loads constitution.technical.md; their FRONTEND lane loads constitution.ui.md. Re-run /appweaver constitution to amend, including to pick up a lane declared or dropped after this run — re-run /appweaver select-stack first to change which lanes exist."

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

@@ -66,4 +66,7 @@ outputs:
   tree_file: "{{tree_file}}"
   sequence_file: "{{sequence_file}}"
   note: "Migration Hierarchy Tree generated in {{tree_file}} and {{sequence_file}}."
-  next: "Human Gate H0.1: Review specs/migration-tree.md and proceed to /appweaver mr per slice."
+  # Migration is a MODE of the ordinary brownfield loop, not a pipeline of its own:
+  # the tree only fixes the ORDER the slices are taken in, and each slice then runs
+  # adopt → (characterize on touch) → the CR delta loop like any other.
+  next: "Human Gate H0.1: Review {{tree_file}} — it orders {{aggregate_count}} aggregate(s) into {{wave_count}} migration wave(s), and that order is the only thing it decides. Take the slices in it ONE AT A TIME through the ordinary brownfield loop: /appweaver adopt <Feature> reverse-engineers the slice into spec.md + backend-plan.md + source-map.md, then every change to it goes through the CR delta loop (/appweaver specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta). If the slice has untested legacy behaviour with blast radius, run /appweaver characterize first to fence it. /appweaver parity is the cutover gate — run it per slice before the seam is routed away from the legacy path."