aw-spec-cli 0.1.26 → 0.1.27

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

@@ -124,6 +124,15 @@ class Stop(Exception):
     pass
 
 
+class Return(Exception):
+    """A gate's `return` outcome: end the module being included and carry on with the
+    step after the `include`. A Stop ends the whole skill, which is wrong for a caller
+    that runs one module per lane — the frontend lane must still run when the backend's
+    scaffold was declined. At the top level of a workflow it ends the run normally, with
+    the outputs resolved, rather than as a stop."""
+    pass
+
+
 class Suspend(Exception):
     """Raised in checkpoint mode when a generation is needed: the interpreter
     persists state and exits so the INVOKING agent can fulfill the request
@@ -231,9 +240,12 @@ class Orchestrator:
         # paths an agent_generate reply named as written that were not on disk —
         # run-cumulative, reported at the end beside missing_required.
         self.reported_missing = []
+        # agent_author targets a --dry-run left unwritten; required_files gates
+        # count them as present, so a dry run reaches the steps after them.
+        self.dry_run_unwritten = []
         self.last_result = {}
         # agent-specific transport profile (None in mock mode). This engine is
-        # general — the profile (loaded from a .claude/.agents/.kilocode file)
+        # general — the profile (loaded from a .claude/.agents/.kilo file)
         # describes HOW to spawn that agent's fresh generation CLI.
         self.profile = getattr(opts, "profile", None)
         # checkpoint transport (run-skill.py method): replay + response cache
@@ -545,7 +557,7 @@ class Orchestrator:
         Returns (structured, raw).
 
         The engine is agent-agnostic: the profile (agent-specific, from a
-        .claude/.agents/.kilocode file) declares the CLI to spawn. A SEPARATE
+        .claude/.agents/.kilo file) declares the CLI to spawn. A SEPARATE
         process → a brand-new conversation that does NOT inherit this
         orchestrator's transcript. The profile maps our neutral knobs
         (system / user / tools / permission_mode / isolation / model / budget)
@@ -553,6 +565,34 @@ class Orchestrator:
         if self.opts.transport == "mock":
             # No model call. The banner (already printed) is the demonstration.
             return None, None
+        argv, stdin_data = self._fresh_command(system, user, tools, permission_mode, model)
+
+        if self.opts.dry_run:
+            # Safety net: every model step prints its command through _mock_step and
+            # takes its mock result, so a dry run never reaches here — and must never
+            # execute if a new caller does.
+            self._emit_fresh_command(argv, stdin_data)
+            raise Stop("dry-run: command shown above (nothing executed)")
+
+        proc = subprocess.run(argv, input=stdin_data, capture_output=True, text=True)
+        if proc.returncode != 0:
+            raise Stop(f"fresh agent failed ({proc.returncode}): {proc.stderr.strip()[:500]}")
+        try:
+            obj = json.loads(proc.stdout)
+        except Exception:
+            return _extract_json(proc.stdout), proc.stdout  # text-output fallback
+        raw = ""
+        for k in (self.profile or {}).get("result_keys", ["result"]):
+            if isinstance(obj, dict) and obj.get(k):
+                raw = obj[k]
+                break
+        if not raw:
+            raw = proc.stdout
+        return _extract_json(raw), raw
+
+    def _fresh_command(self, system, user, tools, permission_mode, model=None):
+        """The argv (and stdin, or None) for one fresh generation, built from the
+        PROFILE's neutral knobs — shared by the real run and the dry-run print."""
         prof = self.profile or {}
         argv = [prof["bin"]] + list(prof.get("args", []))
         model = model or self.opts.model   # per-step `model:` beats --model
@@ -584,29 +624,32 @@ class Orchestrator:
             argv += [umode.get("flag", "-p"), prompt_user]
         else:
             stdin_data = prompt_user
-
-        if self.opts.dry_run:
-            shown = [a if len(a) < 120 else f"<{len(a)} chars>" for a in argv]
-            self.emit(f"[dry-run] {prof.get('name', '?')} would run:\n  " + " ".join(shown))
-            if stdin_data is not None:
-                self.emit(f"[dry-run] + stdin: {len(stdin_data)} chars")
-            raise Stop("dry-run: command shown above (nothing executed)")
-
-        proc = subprocess.run(argv, input=stdin_data, capture_output=True, text=True)
-        if proc.returncode != 0:
-            raise Stop(f"fresh agent failed ({proc.returncode}): {proc.stderr.strip()[:500]}")
-        try:
-            obj = json.loads(proc.stdout)
-        except Exception:
-            return _extract_json(proc.stdout), proc.stdout  # text-output fallback
-        raw = ""
-        for k in prof.get("result_keys", ["result"]):
-            if isinstance(obj, dict) and obj.get(k):
-                raw = obj[k]
-                break
-        if not raw:
-            raw = proc.stdout
-        return _extract_json(raw), raw
+        return argv, stdin_data
+
+    def _emit_fresh_command(self, argv, stdin_data):
+        """Print the command a dry run would have executed (long args elided)."""
+        shown = [a if len(a) < 120 else f"<{len(a)} chars>" for a in argv]
+        self.emit(f"[dry-run] {(self.profile or {}).get('name', '?')} would run:\n  "
+                  + " ".join(shown))
+        if stdin_data is not None:
+            self.emit(f"[dry-run] + stdin: {len(stdin_data)} chars")
+
+    def _mock_step(self, strat, system, user, tools, permission_mode, model=None):
+        """True when a model step takes its mock result instead of running: the
+        mock transport, or --dry-run under spawn/sdk/sdk-apply. A dry run first
+        prints the request the profile would send, then lets the step carry on
+        with its mock result, so one dry run prints every model step's command.
+        The agent strategy is left alone: the invoking agent fulfils it."""
+        if self.opts.transport == "mock":
+            return True
+        if not self.opts.dry_run or strat == "agent":
+            return False
+        if strat in ("sdk", "sdk-apply"):
+            self._emit_sdk_request(system, user, tools, permission_mode)
+        else:
+            self._emit_fresh_command(
+                *self._fresh_command(system, user, tools, permission_mode, model))
+        return True
 
     def _ensure_sdk_module(self, module_name, package_name):
         """Import the profile-declared sdk module; if missing, optionally pip
@@ -663,6 +706,35 @@ class Orchestrator:
             raise Stop(f"sdk adapter {path} must export generate(request)")
         return fn
 
+    def _sdk_config(self):
+        """(module, package, adapter) from the profile's sdk block — a dry run
+        checks them too, so it catches a profile that cannot run sdk/sdk-apply."""
+        if not self.profile:
+            raise Stop("strategy 'sdk'/'sdk-apply' needs --agent-profile — the "
+                       "profile's sdk block declares the SDK to use (the engine "
+                       "has no default agent)")
+        sdk_cfg = self.profile.get("sdk") or {}
+        module_name = sdk_cfg.get("module")
+        package_name = sdk_cfg.get("package")
+        adapter_rel = sdk_cfg.get("adapter")
+        missing = [k for k, v in (("module", module_name), ("package", package_name),
+                                  ("adapter", adapter_rel)) if not v]
+        if missing:
+            raise Stop(f"agent profile '{self.profile.get('name', '?')}': sdk block "
+                       f"is missing {', '.join(missing)} — strategy 'sdk'/'sdk-apply' "
+                       "is fully profile-driven (no built-in default); declare the "
+                       "sdk module/package to import and the adapter file that "
+                       "drives it")
+        return module_name, package_name, adapter_rel
+
+    def _emit_sdk_request(self, system, user, tools, permission_mode):
+        """Print the SDK request a dry run would have sent."""
+        module_name, package_name, adapter_rel = self._sdk_config()
+        self.emit(f"[dry-run] sdk would run: module={module_name}  "
+                  f"package={package_name}  adapter={adapter_rel}  "
+                  f"system={len(system)} chars  user={len(user)} chars  "
+                  f"tools={tools or '(none)'}  permission_mode={permission_mode}")
+
     def _run_sdk(self, system, user, tools, permission_mode, model=None):
         """Strategy 1/2 executor: an isolated generation via the agent's SDK.
         Each call is a NEW session — the only context is the payload we pass
@@ -680,28 +752,12 @@ class Orchestrator:
                              SDK's calling convention (sync or async)
         Everything is imported lazily so the engine stays stdlib-only
         otherwise."""
-        if not self.profile:
-            raise Stop("strategy 'sdk'/'sdk-apply' needs --agent-profile — the "
-                       "profile's sdk block declares the SDK to use (the engine "
-                       "has no default agent)")
-        sdk_cfg = self.profile.get("sdk") or {}
-        module_name = sdk_cfg.get("module")
-        package_name = sdk_cfg.get("package")
-        adapter_rel = sdk_cfg.get("adapter")
-        missing = [k for k, v in (("module", module_name), ("package", package_name),
-                                  ("adapter", adapter_rel)) if not v]
-        if missing:
-            raise Stop(f"agent profile '{self.profile.get('name', '?')}': sdk block "
-                       f"is missing {', '.join(missing)} — strategy 'sdk'/'sdk-apply' "
-                       "is fully profile-driven (no built-in default); declare the "
-                       "sdk module/package to import and the adapter file that "
-                       "drives it")
+        module_name, package_name, adapter_rel = self._sdk_config()
+        sdk_cfg = self.profile.get("sdk") or {}   # handed to the adapter whole
 
         if self.opts.dry_run:
-            self.emit(f"[dry-run] sdk would run: module={module_name}  "
-                      f"package={package_name}  adapter={adapter_rel}  "
-                      f"system={len(system)} chars  user={len(user)} chars  "
-                      f"tools={tools or '(none)'}  permission_mode={permission_mode}")
+            # Safety net, as in _run_fresh: _mock_step prints the request first.
+            self._emit_sdk_request(system, user, tools, permission_mode)
             raise Stop("dry-run: sdk request shown above (nothing executed)")
 
         self._ensure_sdk_module(module_name, package_name)
@@ -839,7 +895,10 @@ class Orchestrator:
         user, ctx_files = self._assemble_user(instr, extra=extra)
         self._print_envelope("agent_generate", system, sys_files, user, ctx_files, tools, strat)
 
-        if self.opts.transport == "mock":
+        # sdk-apply's generation is the read-only one; the dry run shows that request
+        sent_tools, sent_mode = (("Read", "readonly") if strat == "sdk-apply"
+                                 else (tools, permission_mode))
+        if self._mock_step(strat, system, user, sent_tools, sent_mode, step.get("model")):
             structured = self._mock_generate(task)
         elif strat == "agent":
             self._suspend("agent_generate", ck, system, user, tools, permission_mode)
@@ -853,7 +912,9 @@ class Orchestrator:
         else:  # spawn
             structured, _ = self._run_fresh(system, user, tools, permission_mode,
                                             model=step.get("model"))
-        if self.checkpoint:
+        # A dry run's result is a mock: caching it would let a later run without
+        # --dry-run replay it as if a model had produced it.
+        if self.checkpoint and not self.opts.dry_run:
             self.cache[ck] = structured
         structured = self._written_only(step, structured)
         self.last_result = structured
@@ -893,7 +954,7 @@ class Orchestrator:
         # No file tools by default: the files under review are already in the payload.
         self._print_envelope("agent_review", system, sys_files, user, ctx_files, tools, strat)
 
-        if self.opts.transport == "mock":
+        if self._mock_step(strat, system, user, tools, "readonly", step.get("model")):
             # mock: pass if every reviewed file exists
             ok = all(os.path.exists(r) for r in review_of)
             structured = {"pass": ok, "issues": ([] if ok else ["missing output file(s)"])}
@@ -907,7 +968,7 @@ class Orchestrator:
             structured, _ = self._run_fresh(system, user, tools, "readonly",
                                             model=step.get("model"))
         self.last_result = structured
-        if self.checkpoint:
+        if self.checkpoint and not self.opts.dry_run:   # never cache a dry run's mock
             self.cache[ck] = structured
         self._bind(step, structured)
         self.emit(f"[agent_review] strategy={strat or 'mock'} "
@@ -988,10 +1049,23 @@ class Orchestrator:
         self.emit(f"[execute_script] -> {json.dumps(data)[:200]}")
 
     # -- F2: gates ---------------------------------------------------------------
+    def _gate_failed(self, p, outcome, msg):
+        """Apply a failed gate's outcome: `stop` ends the skill, `return` ends the module
+        being included (see Return), anything else continues. `message_var` binds the
+        resolved message first, so a caller that continues or returns can still report
+        why — a message that only reaches the run log is not seen by the operator."""
+        if p.get("message_var"):
+            self.vars[p["message_var"]] = msg
+        if outcome == "stop":
+            raise Stop(msg)
+        if outcome == "return":
+            raise Return(msg)
+
     def act_verify_context(self, step):
         """F2 — the four decl gate forms: required_files (+allow_missing),
         require_non_empty (+on_empty), require_true (+on_false),
-        require_value/equals (+on_mismatch). Messages interpolate {{vars}}."""
+        require_value/equals (+on_mismatch). Messages interpolate {{vars}}.
+        Outcomes: stop | return | continue; `message_var` binds a failed gate's message."""
         p = step.get("parameters") or step
         if p.get("require_non_empty"):
             var = p["require_non_empty"]
@@ -999,8 +1073,7 @@ class Orchestrator:
             if not val:
                 msg = self.resolve(p.get("on_empty_message", f"{var} is empty"))
                 self.emit(f"[verify_context] {var} is empty: {msg}")
-                if p.get("on_empty") == "stop":
-                    raise Stop(msg)
+                self._gate_failed(p, p.get("on_empty"), msg)
             else:
                 self.emit(f"[verify_context] {var} non-empty")
         if p.get("require_true"):
@@ -1011,8 +1084,7 @@ class Orchestrator:
             if not truthy:
                 msg = self.resolve(p.get("on_false_message", f"{var} is not satisfied"))
                 self.emit(f"[verify_context] gate failed ({var}): {msg}")
-                if p.get("on_false", "stop") == "stop":
-                    raise Stop(msg)
+                self._gate_failed(p, p.get("on_false", "stop"), msg)
             else:
                 self.emit(f"[verify_context] gate ok ({var})")
         if p.get("require_value"):
@@ -1022,14 +1094,15 @@ class Orchestrator:
             if actual != expected:
                 msg = self.resolve(p.get("on_mismatch_message", f"{var} != {expected}"))
                 self.emit(f"[verify_context] value gate failed ({var}={actual!r}): {msg}")
-                if p.get("on_mismatch", "stop") == "stop":
-                    raise Stop(msg)
+                self._gate_failed(p, p.get("on_mismatch", "stop"), msg)
             else:
                 self.emit(f"[verify_context] value gate ok ({var}=={expected})")
         for rf in p.get("required_files", []) or []:
             rf = self.resolve(rf)
             if rf in self.loaded or os.path.exists(rf):
                 self.emit(f"[verify_context] present {rf}")
+            elif rf in self.dry_run_unwritten:
+                self.emit(f"[verify_context] present {rf} (dry-run: its author step did not write it)")
             elif p.get("allow_missing"):
                 self.emit(f"[verify_context] missing (allowed) {rf}")
             else:
@@ -1124,7 +1197,7 @@ class Orchestrator:
         system, sys_files = self._assemble_system(p.get("include_standards", True))
         user, ctx_files = self._assemble_user(instr, extra=extra)
         self._print_envelope("agent_author", system, sys_files, user, ctx_files, tools, strat)
-        if self.opts.transport == "mock":
+        if self._mock_step(strat, system, user, tools, "readonly", step.get("model")):
             content = self._mock_author(target, task)
         elif strat == "agent":
             self._suspend("author", ck, system, user, tools, "readonly",
@@ -1148,7 +1221,16 @@ class Orchestrator:
             if not content.strip():
                 raise Stop(f"step {step.get('id')}: agent_author returned empty content")
         if self.opts.dry_run:
+            # The target can be a real project file, so a dry run never writes it.
+            # A later required_files gate counts it as present, and the step's
+            # outputs still bind, so the run reaches the steps after it.
             self.emit(f"[agent_author] dry-run: not writing {target}")
+            if target not in self.dry_run_unwritten:
+                self.dry_run_unwritten.append(target)
+            structured = {"status": "ok", "files": [target],
+                          "summary": f"dry-run: {target} not written"}
+            self.last_result = structured
+            self._bind(step, structured)
             return
         self._write_target(target, content)
         structured = {"status": "ok", "files": [target], "summary": f"authored {target}"}
@@ -1205,14 +1287,14 @@ class Orchestrator:
         system, sys_files = self._assemble_system(p.get("include_standards", True))
         user, ctx_files = self._assemble_user(instr, extra=extra)
         self._print_envelope("agent_query", system, sys_files, user, ctx_files, tools, strat)
-        if self.opts.transport == "mock":
+        if self._mock_step(strat, system, user, tools, "readonly", step.get("model")):
             structured = self.resolve_value(p.get("mock")) or {}
         elif strat == "agent":
             self._suspend("agent_query", ck, system, user, tools, "readonly")
         else:
             structured = self._structured_fresh(step, strat, system, user, tools)
         self.last_result = structured
-        if self.checkpoint:
+        if self.checkpoint and not self.opts.dry_run:   # never cache a dry run's mock
             self.cache[ck] = structured
         self._bind(step, structured)
         self.emit(f"[agent_query] strategy={strat or 'mock'} "
@@ -1381,7 +1463,8 @@ class Orchestrator:
         """F9 — run a module .orch.yaml inline: shares vars, envelope, sticky
         standards, the caller's scripts map and the replay cache. `with:` seeds
         module inputs; cache keys are namespaced under the include id. Stop
-        propagates to the caller (module gates stop the whole skill)."""
+        propagates to the caller (module gates stop the whole skill); a gate's
+        `return` outcome ends only this module and the caller carries on."""
         module_path = self.resolve(step.get("module", ""))
         for k, v in (step.get("with", {}) or {}).items():
             self.vars[k] = self.resolve_value(v)
@@ -1398,6 +1481,8 @@ class Orchestrator:
         self.key_stack.append("inc:" + step.get("id", "include"))
         try:
             self._run_steps(mod.get("workflow", []) or [])
+        except Return as r:
+            self.emit(f"[include] {module_path} returned early: {str(r)[:200]}")
         finally:
             self.key_stack.pop()
 
@@ -1494,7 +1579,10 @@ class Orchestrator:
 
     def run(self):
         self._bind_inputs()
-        self._run_steps(self.wf.get("workflow", []) or [])
+        try:
+            self._run_steps(self.wf.get("workflow", []) or [])
+        except Return as r:
+            self.emit(f"[return] workflow ended early: {str(r)[:200]}")
         return {"status": "ok", "outputs": self.resolve(self.wf.get("outputs", {}) or {}),
                 "vars": self.vars, "missing_required": list(self.missing_required),
                 "reported_not_written": list(self.reported_missing)}
@@ -1510,6 +1598,7 @@ KNOWN_ACTIONS = {
     "dispatch_hooks", "user_select", "ask", "loop", "break", "include",
 }
 STRATEGIES = {"sdk", "sdk-apply", "spawn", "agent"}
+GATE_OUTCOMES = {"stop", "return", "continue"}
 # engine-produced vars a workflow may reference without declaring: the loop/ask
 # bindings, plus the context-assembly miss report (_collect_files, item H).
 _SPECIAL_VARS = {"selection", "answer", "iteration",
@@ -1606,6 +1695,8 @@ def validate_workflow(wf, base_dir, path=""):
                 produced.update((s.get("vars") or s.get("parameters") or {}).keys())
             elif act == "build_context":
                 produced.update((s.get("vars") or {}).keys())
+            elif act == "verify_context" and p.get("message_var"):
+                produced.add(p["message_var"])
             elif act == "loop":
                 produced.add(s.get("as", "item"))
                 produced.add(s.get("as", "item") + "_index")
@@ -1650,6 +1741,13 @@ def validate_workflow(wf, base_dir, path=""):
             warnings.append(f"{loc}: ask has no options source (free-text input)")
         if action == "user_select" and not p.get("options_from_variable"):
             errors.append(f"{loc}: user_select needs options_from_variable")
+        if action == "verify_context":
+            # Any value other than stop/return continues, so a misspelt outcome is a gate
+            # that silently never fires.
+            for k in ("on_empty", "on_false", "on_mismatch"):
+                if p.get(k) is not None and p[k] not in GATE_OUTCOMES:
+                    errors.append(f"{loc}: {k} '{p[k]}' is not a gate outcome "
+                                  f"(known: {', '.join(sorted(GATE_OUTCOMES))})")
         if action == "include":
             m = step.get("module")
             if not m:
@@ -1766,13 +1864,14 @@ def main(argv=None):
                          "real = spawn the agent profile's CLI per generation")
     ap.add_argument("--agent-profile", default="", dest="agent_profile",
                     help="path to an agent transport profile JSON "
-                         "(.claude/.agents/.kilocode/...); implies --transport real")
+                         "(.claude/.agents/.kilo/...); implies --transport real")
     ap.add_argument("--isolation", choices=["bare", "fresh"], default="bare",
                     help="selects the profile's isolation.<mode> args (bare = strongest)")
     ap.add_argument("--model", default="", help="model alias/name for the fresh agent")
     ap.add_argument("--budget", default="", help="value for the profile's budget_flag, if it declares one")
     ap.add_argument("--dry-run", action="store_true", dest="dry_run",
-                    help="print the exact command the profile would run, without executing")
+                    help="print the exact command the profile would run for every model "
+                         "step, without executing any; each step then takes its mock result")
     ap.add_argument("--sdk-install", action="store_true", dest="sdk_install",
                     help="if the profile's sdk module isn't importable, pip install "
                          "the package its sdk block declares, then continue")

package/assets/.appweaver/orchestrator/rev-templates/domain-constitution.skeleton.md

@@ -1,6 +1,6 @@
 <!--
   rev-templates/domain-constitution.skeleton.md — SHAPE-ONLY reference for the
-  domain-constitution SOURCE (guardrails/projects/[project]/domain/domain-constitution.md),
+  domain-constitution SOURCE (guardrails/[project]/domain/domain-constitution.md),
   the human-readable
   charter the domain half is authored from (so the normal /appweaver
   constitution can re-derive it later). It shows the Project-Identity + Domain-
@@ -60,4 +60,4 @@ Extends technology [principle ref]. Evidence: [ids]. → [rule file(s)]
 
 ## Domain Requirements Pointer
 
-→ guardrails/projects/[project]/domain/domain-requirements.md
+→ guardrails/[project]/domain/domain-requirements.md

package/assets/.appweaver/orchestrator/rev-templates/domain-requirements.skeleton.md

@@ -27,8 +27,8 @@ generated_by: aw-spec-onboard/[VERSION]
 =====================================================================
 [DOMAIN: subsection pointers]
 =====================================================================
-[DOMAIN: <subsection>]        -> guardrails/projects/[project]/domain/[generated-file].md
-[DOMAIN: <subsection>]        -> guardrails/projects/[project]/domain/[generated-file].md
+[DOMAIN: <subsection>]        -> guardrails/[project]/domain/[generated-file].md
+[DOMAIN: <subsection>]        -> guardrails/[project]/domain/[generated-file].md
 [DOMAIN: Platform Topology]   -> below
 
 =====================================================================

package/assets/.appweaver/orchestrator/rev-templates/domain-rule-bindings.skeleton.md

@@ -19,7 +19,7 @@ domain principles), and the **gates** (conformance checklist). **plan** and **im
 **NO** domain file — the domain reaches them solely through the spec's ids and the context's
 domain-model.md. This is the rule partition; preserve it exactly.
 
-- All paths are workspace-relative and live in `guardrails/projects/[project]/domain/`.
+- All paths are workspace-relative and live in `guardrails/[project]/domain/`.
 - `resolve-domain --command <name>` collects the `- ` bullets under `## /<name>`.
 
 ---
@@ -27,13 +27,13 @@ domain-model.md. This is the rule partition; preserve it exactly.
 ## /aw-spec-constitution
 <!-- Domain identity / regulatory / interop sources that become domain principles in
      constitution.domain.md. -->
-- guardrails/projects/[project]/domain/[identity-or-requirements-file].md
-- guardrails/projects/[project]/domain/[each generated domain-principle source].md
+- guardrails/[project]/domain/[identity-or-requirements-file].md
+- guardrails/[project]/domain/[each generated domain-principle source].md
 
 ## /aw-spec-specify
 <!-- The FULL generated domain set. Specify models the domain and LIFTS the overlay constraints
      into the spec's CN-/DC-/IC- (plan/implement never see these files). -->
-- guardrails/projects/[project]/domain/[each generated domain rule file].md
+- guardrails/[project]/domain/[each generated domain rule file].md
 
 ## /aw-spec-plan
 _None — plan loads no domain file. Domain reaches plan through the spec and the context's domain-model.md._
@@ -44,7 +44,7 @@ _None — implement loads no domain file. Domain reaches implement through the l
 ## /aw-spec-gate
 <!-- Conformance checklist for the gates (analyze-plan · analyze-slice): the domain-derived
      constraints plan/implement were NOT given as authoring input, VALIDATED against output. -->
-- guardrails/projects/[project]/domain/[each *.domain.md overlay to validate against].md
+- guardrails/[project]/domain/[each *.domain.md overlay to validate against].md
 
 ---
 

package/assets/.appweaver/orchestrator/rev-templates/frontend-rule-file.skeleton.md

@@ -6,7 +6,7 @@ concern: "[concern-slug]"
 <!--
   rev-templates/frontend-rule-file.skeleton.md — SHAPE-ONLY reference for ONE
   generated FRONTEND LANE rule file in the project's frontend/ folder
-  (guardrails/projects/[project]/frontend/<concern>.md). It is the lane's twin of
+  (guardrails/[project]/frontend/<concern>.md). It is the lane's twin of
   technical-rule-file.skeleton.md, and it exists separately because the lane is a
   different tier: these files are ratified by constitution.ui.md's UX-* series,
   not by the technical half's numerals, and they govern only the code under the

package/assets/.appweaver/orchestrator/rev-templates/tech-rule-bindings.skeleton.md

@@ -7,9 +7,9 @@
   placeholder for a service/ file the author actually generated from THIS
   project's CODE.
 
-  Wire ONLY files you generated (all under guardrails/projects/[project]/service/).
+  Wire ONLY files you generated (all under guardrails/[project]/service/).
   Never list a file you did not write. Never list a path belonging to another
-  project (guardrails/projects/<other>/**) — that one is another project's
+  project (any other project folder under guardrails/, e.g. guardrails/project-specific/**) — that one is another project's
   rules, not this one's.
 -->
 # [PROJECT_NAME] — Command → Technical-Rule-File Map (as-built)
@@ -21,11 +21,11 @@ files), and the CODE-DERIVED replacement for the greenfield technical map.
 
 **The model:** the technical rule files (this project's own architecture / persistence /
 concurrency / testing / security-posture set, reverse-engineered from the code into
-`guardrails/projects/[project]/service/`) are CONFIGURATION — tune this map, not the workflows. The
+`guardrails/[project]/service/`) are CONFIGURATION — tune this map, not the workflows. The
 technology base itself (`constitution.technical.md`) is NOT listed here — every consumer still
 refers to it directly, as-is.
 
-- All paths are workspace-relative and live in `guardrails/projects/[project]/service/`.
+- All paths are workspace-relative and live in `guardrails/[project]/service/`.
 - `resolve-tech --command <name>` collects the `- ` bullets under `## /<name>`.
 - **`## /aw-spec-specify` is the MODELLING-METHODOLOGY slot** — exactly one file,
   `service/domain-modelling.md`: HOW this code expresses a domain model. Never an architecture /
@@ -41,39 +41,39 @@ refers to it directly, as-is.
      (what marks an aggregate root, entity vs value object, where invariants live, the context
      boundary), NOT what the model is (that is the domain set's domain-model.domain.md, wired
      via domain-rule-bindings). No technology rule may appear under this heading. -->
-- guardrails/projects/[project]/service/domain-modelling.md
+- guardrails/[project]/service/domain-modelling.md
 
 ## /aw-spec-plan
 <!-- The as-built architecture / cross-cutting technical rules the SERVICE lane's plan author
      mediates the spec against. NO domain file here — domain reaches plan only as spec ids and
      the context's domain-model.md. -->
-- guardrails/projects/[project]/service/[as-built-architecture].md
-- guardrails/projects/[project]/service/[each generated architecture/cross-cutting rule].md
+- guardrails/[project]/service/[as-built-architecture].md
+- guardrails/[project]/service/[each generated architecture/cross-cutting rule].md
 
 ## /aw-spec-implement
 <!-- The framework / code-generation rule set the SERVICE lane's generator builds against
      (from backend-plan.md). -->
-- guardrails/projects/[project]/service/[each generated codegen/convention rule].md
+- guardrails/[project]/service/[each generated codegen/convention rule].md
 
 ## /aw-spec-implement-delta
 <!-- The same set for the service lane on the DELTA path. `implement` is one command: it keys
      this heading when it is generating a change's delta plan and the one above when it is
      generating the master, so repeat the bullets here to keep both paths identical. -->
-- guardrails/projects/[project]/service/[each generated codegen/convention rule].md
+- guardrails/[project]/service/[each generated codegen/convention rule].md
 
 ## /aw-spec-build
 <!-- The layering + convention rules the compile-fixer respects. -->
-- guardrails/projects/[project]/service/[as-built-architecture].md
+- guardrails/[project]/service/[as-built-architecture].md
 
 ## /aw-spec-analyze-slice
 <!-- The plan↔code conformance gate's TECHNICAL checklist (validate, don't author). -->
-- guardrails/projects/[project]/service/[testing/convention rule to validate against].md
+- guardrails/[project]/service/[testing/convention rule to validate against].md
 
 ## /aw-spec-adopt
 <!-- Brownfield reverse-engineering: the technical REFERENCE set the reversed BACKEND plan
      mediates the reversed spec ↔ existing code against — the CODE wins, these are reference
      only. A slice's reversed frontend-plan.md is authored under `## /aw-spec-plan-ui`. -->
-- guardrails/projects/[project]/service/[architecture/cross-cutting reference rule].md
+- guardrails/[project]/service/[architecture/cross-cutting reference rule].md
 
 ## /aw-spec-constitution
 <!-- The set the TECHNICAL half of the split constitution is RE-ratified from when /appweaver
@@ -84,12 +84,12 @@ refers to it directly, as-is.
      service/ files that carry a ratifiable standard, NOT every generated file, and NO worked examples/
      sample (the ratified half is one declarative line per principle). NO domain file — the domain
      half's sources are the DOMAIN map's ## /aw-spec-constitution. -->
-- guardrails/projects/[project]/service/[ratifiable technical standard].md
+- guardrails/[project]/service/[ratifiable technical standard].md
 
 ## /aw-spec-run
 <!-- The runtime / execution conventions the app-run step honors — add ONLY if the code evidences
      a runtime/hosting concern file. NOT data-migration (migration is the deferred later phase). -->
-- guardrails/projects/[project]/service/[runtime/hosting rule].md
+- guardrails/[project]/service/[runtime/hosting rule].md
 
 <!-- THE FRONTEND LANE'S THREE HEADINGS. They are NOT written by the step that authors this
      map; onboard's frontend rule-set step APPENDS them here, after the technical headings and

package/assets/.appweaver/orchestrator/rev-templates/technical-constitution.skeleton.md

@@ -46,8 +46,8 @@ Sync Impact Report
   - …
 - Dependent artifacts:
   - constitution.domain.md — ⚠ authored next; continues at [N+1]
-  - guardrails/projects/[project]/domain/domain-constitution.md — [✅/⚠] domain charter source
-  - guardrails/projects/[project]/service/ — [✅/⚠] technical rule set
+  - guardrails/[project]/domain/domain-constitution.md — [✅/⚠] domain charter source
+  - guardrails/[project]/service/ — [✅/⚠] technical rule set
 - TODOs: [none mechanical | …]
 -->
 # [PROJECT_NAME] Constitution — Technical Base

package/assets/.appweaver/orchestrator/rev-templates/technical-rule-file.skeleton.md

@@ -6,7 +6,7 @@ concern: "[concern-slug]"
 <!--
   rev-templates/technical-rule-file.skeleton.md — SHAPE-ONLY reference for ONE
   generated technical rule file in the project's service/ folder
-  (guardrails/projects/[project]/service/<concern>.md). It is the TECHNICAL twin of
+  (guardrails/[project]/service/<concern>.md). It is the TECHNICAL twin of
   domain-rule-file.skeleton.md. Write one such file per TECHNOLOGY concern the
   CODE ACTUALLY exhibits (evidenced-only, lean) — e.g. as-built-architecture,
   persistence, concurrency, testing, security-posture, api-surface, eventing,

package/assets/.appweaver/orchestrator/rev-templates/ui-constitution.skeleton.md

@@ -59,8 +59,8 @@ Sync Impact Report
 - Experience concerns DELIBERATELY OMITTED (lack of as-built evidence):
   - [CONCERN] — [what the code shows instead, or that it shows nothing]
 - Dependent artifacts:
-  - guardrails/projects/[project]/frontend/ — [✅/⚠] generated lane rule set
-  - guardrails/projects/[project]/tech-rule-bindings.md — [✅/⚠] `## /aw-spec-ui-constitution`
+  - guardrails/[project]/frontend/ — [✅/⚠] generated lane rule set
+  - guardrails/[project]/tech-rule-bindings.md — [✅/⚠] `## /aw-spec-ui-constitution`
 - TODOs: [none mechanical | …]
 -->
 # [PROJECT_NAME] Constitution — User Experience Base
@@ -103,7 +103,7 @@ Sync Impact Report
 <!-- Form: the lane's AS-BUILT layout under its own root — where components, screens/pages,
      routing, client state, styling and assets actually live, named as THIS code names them.
      Do not impose a folder taxonomy the code does not use. This layout sits entirely under
-     the lane's root and never adds to the service lane's structure. -->
+     the lane root folder and never adds to the service lane's structure. -->
 
 ## [UI_CONVENTIONS_SECTION_NAME]