aw-spec-cli 0.1.22 → 0.1.24

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

@@ -88,11 +88,11 @@ the raw object, not its JSON string.
 | action | who runs | what it does |
 |---|---|---|
 | `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:`) |
+| `build_context` | engine | REPLACE the per-request envelope: `system:`/`context:` file lists (+ `context_from: <var>` — or a list of vars, appended in order — holding paths a prior step produced, + `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` 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 |
+| `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 (a JSON object on its last stdout line is still bound, so a gate can show the script's own reason; with none, the 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_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; a reported path not on disk is dropped from `files` (and listed in `files_not_written`) before outputs bind, so a `require_non_empty` gate on it proves something was written. `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}` |
 | `agent_author` | fresh agent | F5 — **authored artifact** (decl `llm_generate`): the INTERPRETER owns `output_target: {type: file, path}`. Generation is payload-only under every strategy (mapped `context:` + sticky envelope + standards are the entire world) and never writes — the ENGINE writes the returned content (sdk-apply degrades to sdk). Optional `context:` (per-request extras), `include_standards: false` (narrow payload), `tools:` (read-only opt-in for a task that names files by path) |
 | `agent_query` | fresh agent | F6 — generic payload-only structured JSON (decl `llm_query`): `schema:` shapes the required fence, `outputs[]` binds it, `mock:` supplies the mock-transport result; one malformed-JSON retry on fresh strategies. Same tools contract as `agent_author` — none unless the step declares `tools:` |

package/assets/.appweaver/RULE-PARTITION.md

@@ -21,9 +21,9 @@ governs. It also stops domain detail leaking straight into code authoring withou
 pinned in a reviewable requirement.
 
 > **Lift, then gate.** If a domain constraint is needed downstream, it must first be *lifted*
-> into the spec as an id. A gate that finds a constraint in neither the spec nor the design
+> into the spec as an id. A gate that finds a constraint in neither the spec nor the plans
 > reports `LIFT-FAILURE:` and routes back to `specify` — it must never invent the rule into a
-> design or into code.
+> plan or into code.
 
 ---
 
@@ -42,13 +42,13 @@ A command with **no heading** in a map loads nothing mapped for that class and
 ### The constitution halves are not mapped
 
 - `.appweaver/memory/constitution.technical.md` — the technology base. Standing input to
-  **design + implement**. Domain-agnostic.
+  the **service lane of `plan` and of `implement`**. Domain-agnostic.
 - `.appweaver/memory/constitution.ui.md` — the **frontend lane's** base, a UX-* principle series.
   Standing input to the **FRONTEND LANE of `plan` and of `implement`**. Domain-agnostic for the same reason the
   technical base is, and it exists only where a frontend lane does — a backend-only project has
   no such file.
 - `.appweaver/memory/constitution.domain.md` — the active domain's addenda. Standing input to
-  **specify** (and the gate checklist). Deliberately **not** loaded by design or implement.
+  **specify** (and the gate checklist). Deliberately **not** loaded by plan or implement.
 - `.appweaver/memory/constitution.md` — the composed human/compatibility view. The pipeline loads
   the halves, not this file.
 
@@ -74,11 +74,13 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
   **HOW to model**; **WHAT** the model is stays in the domain tier.
 - Constitution: the **domain** half.
 
-### `design` — *architecture; domain input = the spec only*
-- **Domain rule files: NEVER.** Domain reaches design solely as spec ids.
-- **Technical rule files: yes** — architecture and cross-cutting rules the design mediates the
-  spec against.
-- Constitution: the **technical** half.
+### `plan` — *architecture, both lanes; domain input = the spec tier only*
+- **Domain rule files: NEVER.** Domain reaches plan solely as spec ids and the context's
+  `domain-model.md`.
+- **Technical rule files: yes** — the architecture and cross-cutting rules each lane's plan
+  mediates the spec against: `## /aw-spec-plan` for the service lane, `## /aw-spec-plan-ui`
+  for the frontend lane.
+- Constitution: the **technical** half in the service lane, the **UI** half in the frontend one.
 
 ### `implement` — *code generation, both lanes, both paths*
 - **Domain rule files: NEVER.** The lane's plan is the only input describing what to BUILD.
@@ -97,7 +99,7 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
 
 ### `build` — *compile + repair*
 - **Technical rule files: yes** — the layering and convention rules the compile-fixer respects.
-- No domain files: build repairs against design intent, which the domain never reaches.
+- No domain files: build repairs against the plans' intent, which the domain never reaches.
 
 ### `run` — *runtime*
 - **Technical rule files:** only if the project evidences a runtime/hosting concern.
@@ -121,23 +123,24 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
 - Authors all three halves itself, and generates the rule set each one ratifies. The rule maps do
   not exist yet when it starts, so its authority is the **code**: every principle and every
   generated rule file is evidenced from source, and a greenfield rule file is never an input.
-- The **UI half** is authored where the **scan** finds a UI — `frontend_signals` reaching lane
-  strength — not where a map heading exists, because at onboard there is no map to read. The
-  order is therefore inverted: the half is authored from the code, then the `frontend/` rule set is
-  generated as its detail layer, then `## /aw-spec-ui-constitution` is appended to the technical
-  map. That heading is what makes every LATER `constitution` run behave like the greenfield case
-  above.
-- A frontend lane declared in `.appweaver/stacks.json` corroborates rather than decides: with no
-  UI source there is nothing to reverse-engineer, so nothing is authored.
-- `onboard` also **records** the lanes it reverse-engineered in `.appweaver/stacks.json`, through
-  `lane-declare` — still the sole writer, now with two callers. A derived lane carries
-  `origin: reverse-engineered` and an existing declaration is never overwritten, so a lane a
-  person confirmed always outranks one a scan proposed. Confirming or correcting a lane stays
-  `select-stack`'s job.
+- **Which lanes exist is the declaration's answer.** `select-stack` runs first and writes
+  `.appweaver/stacks.json`; onboard refuses to start without it. A lane declared there gets its
+  half and its rule set, a lane declared `(none)` gets neither, and the scan — pointed at the
+  declared source path — decides what the governance SAYS, never whether the lane exists. A
+  declared UI lane whose path holds no recognisable UI source is reported, and its governance is
+  authored thin rather than skipped.
+- The **UI half** is authored from the lane's code, not from a map heading, because at onboard
+  there is no map to read. The order is therefore inverted: the half is authored from the code,
+  then the `frontend/` rule set is generated as its detail layer, then the lane's three headings
+  are appended to the technical map — `## /aw-spec-ui-constitution` (what a LATER `constitution`
+  run re-ratifies from, so it behaves like the greenfield case above), `## /aw-spec-plan-ui` and
+  `## /aw-spec-implement-ui` (what the frontend lane of `plan` and `implement` load).
+- `onboard` **never writes** `.appweaver/stacks.json`. `lane-declare` is its sole writer and
+  `select-stack` its only caller, so every lane is one a person confirmed.
 - The **document templates** it derives obey the same partition as the halves that govern them:
-  the service design + delta-design pair is authored against `constitution.technical.md`, the
+  the backend plan + delta pair is authored against `constitution.technical.md`, the frontend
   lane's pair against `constitution.ui.md` and the generated `frontend/` rules, and neither
-  reads a domain file. This is invariant 7 applied one level up — a lane's template describes
+  reads a domain file. The domain-model template is lane-neutral. This is invariant 7 applied one level up — a lane's template describes
   that lane's code and no other's.
 - **No greenfield artifact is ever in context.** Where a step needs a shape reference it reads a
   neutral skeleton from `.appweaver/orchestrator/rev-templates/`, which carries the format and no
@@ -145,19 +148,29 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
   so an instruction not to copy an exemplar would be the only control — absence is the stronger
   one.
 - Ordering is preserved for the same reason as above: technical half → UI half → domain half.
+- **Per bounded context.** The first context to onboard authors every tier above; each later
+  context amends the tiers that exist, additively and from its own code, under the same
+  partition — the service tier's step sees no domain file, the frontend tier's step no service
+  rule file, and the domain tier's step reads the technical half only to continue its
+  numbering. A tier that does not exist yet (a lane declared after an earlier onboard) is
+  authored in full, in the order above. The document templates are written once per lane and
+  never amended.
 
 ### `adopt` (brownfield)
 - Same partition, reversed: the reversed **spec** is authored with domain rules in context; the
-  reversed **design** is authored with the technical set only, so design stays domain-free.
+  reversed **plan** is authored with the technical set only, so the plan stays domain-free.
+- Each lane's reversed plan is authored under its own lane's rules, as in `plan`: the backend
+  plan under `## /aw-spec-adopt`, and the frontend plan under `## /aw-spec-plan-ui`, which
+  REPLACES the backend set before that step rather than stacking on it.
 - Technical files here are **reference, not authority — the CODE wins.**
 
 ---
 
 ## Invariants
 
-1. **No domain rule file is ever loaded by `design`, `implement` or `build`** — on either
+1. **No domain rule file is ever loaded by `plan`, `implement` or `build`** — on either
    lane and on either path.
-2. **Domain reaches design and code only through the SPEC TIER** — as spec ids, and as the
+2. **Domain reaches the plans and code only through the SPEC TIER** — as spec ids, and as the
    bounded context's `domain-model.md` (plus a change's pending model delta) that those ids
    point into. Never as a domain rule file: the rules were resolved into the model and the
    spec at `specify`, and a phase downstream of that reads the resolution, never re-derives

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
@@ -162,6 +163,34 @@ def _extract_json(text):
     return {}
 
 
+def _last_json_line(text):
+    """The object on stdout's LAST line — the script contract — or None when that
+    line is missing or is not a JSON object."""
+    lines = (text or "").strip().splitlines()
+    if not lines:
+        return None
+    try:
+        data = json.loads(lines[-1])
+    except Exception:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _script_reason(data, stderr, returncode):
+    """Why a script failed, in its own words where it gave any. A script that
+    prints `{"ok": "false", "error": …}` and exits non-zero has already said why;
+    stderr is often only its progress log, so the JSON is read first."""
+    data = data or {}
+    for key in ("error", "problems", "message", "reason"):
+        v = data.get(key)
+        if isinstance(v, str) and v.strip():
+            return v.strip()
+    errs = data.get("errors")
+    if isinstance(errs, list) and errs:
+        return "; ".join(str(e) for e in errs)
+    return (stderr or "").strip() or f"exit code {returncode}, no output"
+
+
 def _strip_fence(text):
     """If the ENTIRE reply is one fenced code block, unwrap it (models often
     fence authored file content despite being told not to)."""
@@ -199,6 +228,9 @@ class Orchestrator:
         # assembly time (item H). Distinct, run-cumulative, surfaced in the run
         # result + the context_missing/_count vars so a workflow can gate on it.
         self.missing_required = []
+        # 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 = []
         self.last_result = {}
         # agent-specific transport profile (None in mock mode). This engine is
         # general — the profile (loaded from a .claude/.agents/.kilocode file)
@@ -406,14 +438,21 @@ class Orchestrator:
         against the run-cumulative set (cf. concept-paths' `missing`).
 
         A path that resolves to "" is an unbound {{var}} on this branch, not a
-        missing file — skipped silently, as before."""
+        missing file — skipped silently, as before.
+
+        A file named twice is sent once, compared by the file it resolves to rather
+        than by spelling: a script returns `knowledge/x.md` where a workflow writes
+        `{{bundle_dir}}/x.md` with an absolute bundle_dir, and both are one file."""
         files, seen = [], set()
         for p, optional in entries:
             rp = self.resolve(p)
-            if not rp or rp in seen:
+            if not rp:
+                continue
+            key = os.path.normcase(os.path.realpath(rp))
+            if key in seen:
                 continue
             if os.path.exists(rp):
-                seen.add(rp)
+                seen.add(key)
                 files.append(rp)
             elif optional:
                 self.emit(f"[{kind}] optional missing, skip {rp}")
@@ -693,10 +732,11 @@ class Orchestrator:
     def act_build_context(self, step):
         ctx = list(step.get("context", []) or [])
         # dynamic context: append a var holding a list of paths — e.g. the files a
-        # prior agent_generate reported it wrote (since IT, not we, chose them).
+        # prior agent_generate reported it wrote (since IT, not we, chose them). A list
+        # of var names appends each in order.
         cf = step.get("context_from")
-        if cf:
-            ctx += list(self.vars.get(cf) or [])
+        for name in (cf if isinstance(cf, list) else [cf] if cf else []):
+            ctx += list(self.vars.get(name) or [])
         self.envelope = {"system": step.get("system", []) or [], "context": ctx}
         for k, v in (step.get("vars", {}) or {}).items():
             self.vars[k] = self.resolve(v)
@@ -732,6 +772,30 @@ class Orchestrator:
             v = ",".join(str(x) for x in v)
         return (self.resolve(str(v)) or "").strip()
 
+    def _written_only(self, step, structured):
+        """The generation result with `files` narrowed to paths that exist on disk.
+
+        `files` is the paths the agent SAYS it wrote. Every workflow gates on it with
+        `require_non_empty`, which proved only that the reply named something: a reply
+        listing a file whose write had failed passed the gate, and the next step read
+        a template that was never written. A path that is not on disk is dropped here
+        and announced, so an existing gate stops when nothing real was written, and a
+        step that builds context from the list gets only real files. The unfiltered
+        list stays in the replay cache, so every replay re-checks the disk."""
+        if not isinstance(structured, dict) or not isinstance(structured.get("files"), list):
+            return structured
+        kept, missing = [], []
+        for f in structured["files"]:
+            (kept if isinstance(f, str) and f.strip() and os.path.exists(f) else missing).append(f)
+        if not missing:
+            return structured
+        self.emit(f"[agent_generate] {step.get('id')}: {len(missing)} reported file(s) "
+                  f"not on disk, dropped: {', '.join(str(m) for m in missing)}")
+        for m in missing:
+            if m not in self.reported_missing:
+                self.reported_missing.append(m)
+        return dict(structured, files=kept, files_not_written=missing)
+
     def act_agent_generate(self, step):
         tools = step.get("tools", "Read,Write,Edit,Bash")
         permission_mode = step.get("permission_mode", "acceptEdits")
@@ -742,7 +806,7 @@ class Orchestrator:
         # bind its cached structured result instead of executing again.
         ck = self._key(step)
         if self.checkpoint and ck in self.cache:
-            structured = self.cache[ck]
+            structured = self._written_only(step, self.cache[ck])
             self.last_result = structured
             self._bind(step, structured)
             self.emit(f"[agent_generate] (cached) result={json.dumps(structured)[:200]}")
@@ -789,9 +853,10 @@ class Orchestrator:
         else:  # spawn
             structured, _ = self._run_fresh(system, user, tools, permission_mode,
                                             model=step.get("model"))
-        self.last_result = structured
         if self.checkpoint:
             self.cache[ck] = structured
+        structured = self._written_only(step, structured)
+        self.last_result = structured
         self._bind(step, structured)
         self.emit(f"[agent_generate] strategy={strat or 'mock'} "
                   f"result={json.dumps(structured)[:200]}")
@@ -901,12 +966,18 @@ class Orchestrator:
             return
         proc = subprocess.run(runner + [sub] + args, capture_output=True, text=True)
         if proc.returncode != 0:
+            # A script that fails can still have answered: many print their verdict as
+            # JSON (`ok: false` plus the reason) and exit non-zero. Under `on_error:
+            # continue` that object is bound like a success's, so the gate after the
+            # step reads the script's own reason instead of a blank. A failure with no
+            # JSON binds nothing, as before.
+            data = _last_json_line(proc.stdout)
+            reason = _script_reason(data, proc.stderr, proc.returncode)
             if p.get("on_error") == "continue":
-                self.emit(f"[execute_script] {sub} failed (continuing): "
-                          f"{proc.stderr.strip()[:200]}")
-                self._bind(step, {})
+                self.emit(f"[execute_script] {sub} failed (continuing): {reason[:200]}")
+                self._bind(step, data or {})
                 return
-            raise Stop(f"script failed ({sub}): {proc.stderr.strip()[:500]}")
+            raise Stop(f"script failed ({sub}): {reason[:500]}")
         try:
             data = json.loads(proc.stdout.strip().splitlines()[-1])
         except Exception as e:
@@ -1425,7 +1496,8 @@ class Orchestrator:
         self._bind_inputs()
         self._run_steps(self.wf.get("workflow", []) or [])
         return {"status": "ok", "outputs": self.resolve(self.wf.get("outputs", {}) or {}),
-                "vars": self.vars, "missing_required": list(self.missing_required)}
+                "vars": self.vars, "missing_required": list(self.missing_required),
+                "reported_not_written": list(self.reported_missing)}
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -1491,7 +1563,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 +1693,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 +1824,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 +1846,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:
@@ -1871,7 +1986,8 @@ def main(argv=None):
         return 2
     except Stop as e:
         result = {"status": "stopped", "reason": str(e), "vars": orch.vars,
-                  "missing_required": list(orch.missing_required)}
+                  "missing_required": list(orch.missing_required),
+                  "reported_not_written": list(orch.reported_missing)}
         _clear_checkpoint(opts)
 
     if opts.json:
@@ -1889,6 +2005,12 @@ def main(argv=None):
                   "them was assembled without them:")
             for m in result["missing_required"]:
                 print(f"  - {m}")
+        if result.get("reported_not_written"):
+            print(f"\nWARNING: {len(result['reported_not_written'])} file(s) a generation "
+                  "reported as written are not on disk — dropped from its result, so no "
+                  "later step read them:")
+            for m in result["reported_not_written"]:
+                print(f"  - {m}")
         if result.get("outputs"):
             print(json.dumps(result["outputs"], indent=2))
     return 0 if result["status"] == "ok" else 1

package/assets/.appweaver/orchestrator/rev-templates/ai-rules.reference.md

@@ -12,9 +12,9 @@
 > Pure operating rules — domain-agnostic, stack-agnostic. Applies to every brownfield
 > reverse-engineering authoring step (onboard's constitution + rule-set authors, adopt).
 
-The **code, the deterministic scan, and any adopted spec.md / design.md / source-map.md + the
-OKF bundle are ground truth.** Author only what they evidence; they override any pre-trained
-habit and any greenfield template ideal.
+The **code, the deterministic scan, and any adopted spec.md / backend-plan.md /
+frontend-plan.md / source-map.md + the OKF bundle are ground truth.** Author only what they
+evidence; they override any pre-trained habit and any greenfield template ideal.
 
 ## Evidence discipline
 

package/assets/.appweaver/orchestrator/rev-templates/delta-design-template.skeleton.md

@@ -6,8 +6,8 @@
   TEMPLATE that onboard installs at
   .appweaver/templates/overrides/delta-design-template.md. It carries the neutral
   bones of a change record — the classification triple, the model bridge, the
-  wave discipline, the impact and regression sections, the two ledgers, the merge
-  contract — and NOTHING ELSE.
+  wave discipline, the impact and regression sections, the two ledgers, what
+  happens to the record at merge — and NOTHING ELSE.
 
   IT NAMES NO LAYERING AND NO TECHNOLOGY. The "Section" column below is a SLOT:
   it is filled with the ACTUAL sections of the master plan template generated
@@ -23,9 +23,10 @@
 
   DISCIPLINE THIS SKELETON ENFORCES (structurally — there is no project content
   here to leak):
-    • ONE MASTER PER LANE — a change amends
+    • ONE MASTER PER LANE — a change is planned against
       specs/<Context>/<Feature>/backend-plan.md; it never opens a second plan
-      document, and it never edits the master itself.
+      document and never edits the master. Neither does finalize-delta: the
+      master is re-derived from the merged spec and model by `plan main`.
     • ADDED / MODIFIED / REMOVED — the complete classification. A shared element
       is MODIFIED in place, never duplicated into the change.
     • EVERY ROW SERVES A SPEC ID — the delta reads the delta-spec and the domain
@@ -54,8 +55,11 @@
 
 <!--
   This delta applies to the SINGLE master plan at
-  specs/[Context]/[Feature]/backend-plan.md — never a new plan doc, and never the
-  master itself: finalize-delta merges it later in the chain.
+  specs/[Context]/[Feature]/backend-plan.md — never a new plan doc. It does not
+  touch the master, and neither does finalize-delta: the master is DERIVED from
+  spec.md and domain-model.md, the two documents finalize-delta merges, so
+  `plan main` re-derives it rather than patching it from this file. close-delta
+  archives this document as the record of how the change was built.
 
   IT PLANS AGAINST THE EFFECTIVE MODEL — the master domain-model.md, this change's
   own model delta, and the PREDECESSOR deltas (the open ones in a LOWER wave,
@@ -145,15 +149,18 @@ changed.]
 
 ## New assumptions / deviations (from this change)
 
-<!-- Anything this change defers — folds into the master's DA-n / WA-n ledgers
-     on merge. -->
+<!-- Anything this change defers. It stays this document's record — the master's
+     DA-n / WA-n ledgers are re-derived with the rest of the master plan, not
+     patched from here. -->
 
 - **DA-[n]**: [assumption to clarify later] — or `None`
 - **WA-[n]**: [deviation to clear later] — or `None`
 
 ## On merge
 
-`finalize-delta` merges this record into the master backend-plan.md alongside the
-spec and domain-model merges and leaves the change OPEN; `close-delta` bumps the
-version, writes the Change History rows and archives the change under
-`changes/archive/`.
+`finalize-delta` merges the change's SPEC half into `spec.md` and its MODEL half into the
+context's `domain-model.md`, in one transaction, and leaves the change OPEN. It does NOT
+merge this document: the master plan is derived from those two, so `plan main` re-derives
+it rather than patching it. `close-delta` archives this file with the change, bumps the
+minor version and writes the Change History rows. None of it is this document's job — it
+records the change, it does not apply it.

package/assets/.appweaver/orchestrator/rev-templates/design-template.skeleton.md

@@ -16,10 +16,11 @@
   CODE, never copied.
 
   THIS IS A TEMPLATE OF A TEMPLATE. What onboard generates from it is not a
-  filled design — it is the project's design TEMPLATE, which the forward
-  `design` phase and `adopt` then fill once per feature. So the generated file
-  keeps [PLACEHOLDER] tokens and authoring comments; what onboard replaces is
-  the STRUCTURE (which sections exist, what they are called), not the content.
+  filled plan — it is the project's backend plan TEMPLATE, which the service lane
+  of `plan` and `adopt` then fill once per feature into
+  specs/<Context>/<Feature>/backend-plan.md. So the generated file keeps
+  [PLACEHOLDER] tokens and authoring comments; what onboard replaces is the
+  STRUCTURE (which sections exist, what they are called), not the content.
 
   WHAT IS PINNED, AND WHY (DESIGN-FORMAT.md § Brownfield variant is the
   authority — these are the only fixed points, and each earns it by being
@@ -31,8 +32,8 @@
       lets a derived layout and the greenfield layout be read by one tool.
     • The traceability spine (§4) and both ledgers (§5 DA-n, §6 WA-n) survive
       every layout — the analyze gates read them.
-    • The §0–§6 numbering itself: the forward `design` bootstrap_bf branch
-      names those sections in its prompt.
+    • The §0–§6 numbering itself: `plan`'s bootstrap_bf branch names those
+      sections in its prompt.
   Everything else — how many §2 axes there are, what they are called, what
   lives in each — is the code's answer, not the kit's.
 
@@ -51,13 +52,15 @@
       raises, contracts as field shapes. The stack binds at `implement`.
   ═══════════════════════════════════════════════════════════════════════════
 -->
-# Design: [AGGREGATE]
+# Backend Plan: [FEATURE]
 
-**Feature**: `[Feature]`
+**Feature**: `[Feature]`  <!-- the capability scope the developer chose; the aggregate(s) it acts on are the spec's "Acts on aggregate(s)" line -->
 
 **Plan home**: `specs/[Context]/[Feature]/backend-plan.md`
 
-**Source spec**: `specs/[Aggregate]/spec.md`
+**Source spec**: `specs/[Context]/[Feature]/spec.md`
+
+**Source model**: `specs/[Context]/domain-model.md`   <!-- where the context has one -->
 
 **Version**: v1.0
 
@@ -66,9 +69,10 @@
 <!--
   WHAT THIS DOCUMENT IS
   =====================
-  The single, living High-Level Design for ONE aggregate — the MEDIATOR between
-  spec.md (WHAT/WHY) and the generated code (HOW). It carries structure,
-  contracts, behaviour and decisions; it is not code.
+  The single, living High-Level Design for ONE feature — the capability scope the
+  developer chose, over the aggregate(s) its spec says it acts on — and the
+  MEDIATOR between spec.md (WHAT/WHY) and the generated code (HOW). It carries
+  structure, contracts, behaviour and decisions; it is not code.
 
   ANCHORING RULES
   - Every design element traces UP to an id (FR-/BR-/CN-/DC-/IC-/US-/SC-) and the
@@ -110,11 +114,11 @@
 
 ## 0. Design Overview
 
-<!-- One paragraph: the shape of this aggregate and the 3–5 decisions that
+<!-- One paragraph: the shape of this feature and the 3–5 decisions that
      matter most. The project's standing structural convention is NOT restated
      here — it is §1.1. -->
 
-[The architectural essence of this aggregate in 3–6 sentences.]
+[The architectural essence of this feature in 3–6 sentences.]
 
 ### Ubiquitous Language (design delta)
 
@@ -245,9 +249,13 @@
 
 ## Change History
 
-<!-- In lockstep with spec.md. finalize-delta appends the row when it merges a
-     delta; close-delta bumps the version and stamps it into the header. A
-     change is a DELTA on this document, never a new design doc. Newest last. -->
+<!-- A row is appended when this plan is RE-DERIVED to carry a change: the plan
+     is derived from spec.md and the context's domain-model.md, and finalize-delta
+     merges a change into those two, never into this one (`plan main` re-derives
+     it). close-delta bumps the version and stamps it into the header, so a header
+     ahead of the newest row means the plan has not been re-derived since. A
+     change is planned as a DELTA in the change's own directory, never as a new
+     plan document. Newest last. -->
 
 | Version | Date | Change | User stories | CR |
 |---------|------|--------|--------------|-----|

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

@@ -20,7 +20,7 @@ generated_by: aw-spec-onboard/[VERSION]
 [DOMAIN: Bounded Contexts / Modules]
 =====================================================================
 - [Context / module] — aggregate root: **[Aggregate]** (adopted — current evidence); owns
-  [entities] and the value objects ([named VOs]). See [[domain-driven-design.domain]].
+  [entities] and the value objects ([named VOs]). See [[domain-model.domain]].
 - [Named external reference / port] — [role]; not adopted as an aggregate.
 - [… list each bounded context observed in the OKF overview / aggregate index …]
 
@@ -45,4 +45,4 @@ generated_by: aw-spec-onboard/[VERSION]
 
 ## Related
 
-- [[domain-driven-design.domain]] · [[<generated siblings>]]
+- [[domain-model.domain]] · [[<generated siblings>]]