aw-spec-cli 0.1.19 → 0.1.21

package/assets/.appweaver/DESIGN-FORMAT.md

@@ -36,9 +36,11 @@ behaviour
 FR/US/SC/CN/DC/IC
 ```
 
-- **One design per aggregate.** The four clean-architecture layers (Domain,
+- **One design per feature.** The four clean-architecture layers (Domain,
   Application, API, Infrastructure) are **sections** of this one document, each at
-  design level. Feature = aggregate; commands are user stories inside it. *(This is
+  design level. A feature is a capability scope the developer chooses — it may act on
+  several aggregates, and several features may act on one; its operations are user
+  stories inside it. *(This is
   the **greenfield** layout, authored from `design-template.md`. See the Brownfield
   variant below for reverse-engineered / existing-codebase designs.)*
 - **High-level, not code.** It carries entities/value-objects/events, behaviour as
@@ -170,11 +172,13 @@ the gate and the review able to check coverage, and what keeps CR impact analysi
 
 ## Feature granularity (why a command is a delta, not a new feature)
 
-A **feature is the largest slice whose code no other feature owns.** Because
-`implement` regenerates the whole feature's code coherently, a shared file
-(`src/Domain/Order.cs`) must have exactly **one** owning design. So for an aggregate
-with a shared entity, **feature = the aggregate** (`Order`), and individual commands
-(`CreateOrder`, `UpdateOrder`, …) are **user stories / deltas** on the same backend-plan.md:
+A **feature is a capability scope the developer chooses** — `Order`, or
+`PatientRegistration` beside `PatientMerge`. It may act on several aggregates, and
+several features may act on one. The aggregates live above every feature: in the bounded
+context's `domain-model.md` (one `## Aggregate:` section each) and in the OKF bundle (one
+concept each, listing the features that act on it). An operation inside a feature's scope
+(`CreateOrder`, `UpdateOrder`, …) is a **user story / delta** on that feature's
+backend-plan.md:
 
 - `CreateOrder` = US-1; `UpdateOrder` = US-2.
 - Adding `UpdateOrder` is an additive CR: a **delta-spec** (`+US-2`), the change's own
@@ -192,8 +196,12 @@ with a shared entity, **feature = the aggregate** (`Order`), and individual comm
   version (`v1.0 → v1.1`). The two are deliberately separate so a red `analyze-slice`
   between them is still "fix and re-run" rather than a change that already shipped.
 
-Two command-level features would both claim `src/Domain/Order.cs` and collide —
-which is exactly why the aggregate is the boundary.
+**Shared aggregate code is extended, never regenerated.** When two features act on one
+aggregate, its root, entities and repository (`src/Domain/Order.cs`) are realised by
+both plans: each names only the members its feature needs, and `implement` adds those
+members to the existing file instead of writing it afresh. What a feature owns outright
+is its own use-cases, endpoints and handlers. The invariants are the model's, so two
+features never disagree about them.
 
 ## Migration status
 

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

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

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

@@ -121,8 +121,10 @@ workflow:
         to the standard governing every such behaviour is a UX- delta. A bound the SERVICE
         must meet stays a CN-, because the service-side gates trace CN- and never read the
         Experience Standards.
-      - The new operation is a NEW USER STORY — assign the next id after the highest US-n
-        in the master — never a new feature/aggregate. Record the regression risk (shared
+      - The new operation is a NEW USER STORY of THIS feature — assign the next id after
+        the highest US-n in the master. Whether a capability is its own feature is the
+        developer's decision, made when they chose this feature; never open, name or
+        imply another feature or a new aggregate here. Record the regression risk (shared
         behaviour that must still hold).
       - STRUCTURE IS NOT YOURS TO WRITE HERE. A new entity or value object, a changed
         aggregate boundary, a new domain event, or a new or amended invariant (BR-n) is a
@@ -138,7 +140,7 @@ workflow:
         touches the same aggregate or the same FR ids, say so under "Other open deltas"
         in Impact. If THIS change only makes sense after one of them lands, say so in the
         Wave rationale — that is a wave dependency, and the wave must then be RAISED above
-        that delta's (report it; `cr-wave` applies it). Do not silently assume their
+        that delta's — name it under `## Depends on` and the wave is raised from that. Do not silently assume their
         changes: until merged they are proposals, not the master.
       - Do NOT edit the Wave / Created / Base version headers — scripts stamp those.
       Change request: {{USER_INPUT}}
@@ -181,4 +183,25 @@ workflow:
         entry MUST sit in a LOWER wave than this delta ({{wave}}). "None" when it stands
         alone. Reading another delta is NOT depending on it — only assuming its changes is.
       - Do NOT edit the Wave / Created / Base context version headers — scripts stamp those.
+        Naming a delta under "## Depends on" is what RAISES this change's wave, immediately
+        after you write it; you never set the number yourself.
       Change request: {{USER_INPUT}}
+
+  # 4. THE WAVE THE DOCUMENTS THEMSELVES IMPLY. cr-setup stamped a provisional wave before
+  #    either half existed — the highest already open, which is right for a change that
+  #    stands alone and wrong for one that builds on another: it lands at its predecessor's
+  #    wave, where the blocker fence reads the two as independent and lets them merge in
+  #    either order. Now that "## Depends on" is written, that declaration decides: the wave
+  #    is raised to one above the highest delta named there, in BOTH halves, so the number
+  #    and the prose cannot drift apart. A change that names none keeps what it has, and one
+  #    already sitting higher is left alone. The merge fence re-checks the same rule.
+  - id: derive_wave
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: cr-wave-derive
+    args: ["--cr-id", "{{cr_id}}", "--stamp"]
+    outputs:
+      - { name: wave,         from: "$.wave" }
+      - { name: wave_depends, from: "$.depends_on" }
+      - { name: wave_message, from: "$.message" }

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

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

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

@@ -40,7 +40,7 @@
 -->
 # Delta Backend Plan — [CR-ID]: [TITLE]
 
-**Feature (aggregate slice)**: [Feature]
+**Feature**: [Feature]
 
 **Lane**: backend
 

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

@@ -53,7 +53,7 @@
 -->
 # Design: [AGGREGATE]
 
-**Aggregate (feature)**: `[Aggregate]`
+**Feature**: `[Feature]`
 
 **Plan home**: `specs/[Context]/[Feature]/backend-plan.md`
 
@@ -81,7 +81,9 @@
     aggregate boundary and the BR-nnn invariants; where it does not, the spec
     carries that structure alone. A domain rule neither states is recorded as a
     §5 assumption, never smuggled in.
-  - Feature = aggregate. A later requirement is a DELTA on this document.
+  - One feature = one plan. A feature is the capability scope the developer chose
+    and may act on several aggregates, as several features may act on one. A later
+    requirement on this feature is a DELTA on this document.
 
   STRUCTURE FOLLOWS THIS PROJECT'S CODE
   - [GENERATED_STRUCTURE_NOTE] — form: one or two sentences naming the

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

@@ -37,7 +37,7 @@
 -->
 # Delta Frontend Plan — [CR-ID]: [TITLE]
 
-**Feature (aggregate slice)**: [Feature]
+**Feature**: [Feature]
 
 **Base version**: [vX.Y]
 

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

@@ -59,7 +59,7 @@
 -->
 # UI Design: [AGGREGATE]
 
-**Aggregate (feature)**: `[Aggregate]`
+**Feature**: `[Feature]`
 
 **Plan home**: `specs/[Context]/[Feature]/frontend-plan.md`
 

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

@@ -189,7 +189,7 @@ workflow:
     action: verify_context
     require_non_empty: feature_name
     on_empty: stop
-    on_empty_message: "No feature to adopt. Either run /appweaver select-feature first (pick the aggregate from the onboard feature map), then /appweaver adopt; or name it directly: /appweaver adopt <Feature>."
+    on_empty_message: "No feature to adopt. Either run /appweaver select-feature first (pick the feature from the boundary map onboard laid out), then /appweaver adopt; or name it directly: /appweaver adopt <Feature>."
 
   # WHICH BOUNDED CONTEXT THIS FEATURE LANDS IN, and a refusal to guess — the same gate
   # select-feature carries, and needed here for the same reason: this stage also creates a
@@ -234,6 +234,26 @@ workflow:
       - { name: spec_file,    from: "$.spec_file" }
       - { name: spec_exists,  from: "$.spec_exists" }
 
+  # WHICH AGGREGATE THIS FEATURE ACTS ON. Usually the same name — one aggregate, one
+  # feature, the 1:1 default — but not when the boundary map split an aggregate into
+  # capabilities (PatientRegistration and PatientMerge over Patient). The reverse steps
+  # below write and judge the model section BY THIS NAME, and every later command finds
+  # the feature's part of the model the same way; writing it under the feature's name
+  # instead defines one root twice as soon as a sibling feature is adopted. No spec
+  # exists yet at this point, so it resolves from the confirmed boundary map, and a
+  # feature the map does not split resolves to its own name — exactly what this
+  # workflow always used.
+  - id: feature_aggregates
+    action: execute_script
+    script: { ref: xref }
+    subcommand: feature-aggregates
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: aggregates_csv,     from: "$.aggregates_csv" }
+      - { name: aggregate_sections, from: "$.sections" }
+      - { name: aggregate_source,   from: "$.source" }
+      - { name: aggregate_primary,  from: "$.primary" }   # the concept this feature's OKF work lands on
+
   # 1a. One-time baseline: refuse to clobber an already-adopted / authored spec.
   #     After adoption, changes go through the CR delta loop, not adopt.
   #     set-feature returns spec_exists as a JSON boolean; the condition path
@@ -247,14 +267,16 @@ workflow:
     on_empty: stop
     on_empty_message: "specs/ already has a spec.md for {{feature_name}} — adopt is a one-time baseline. For a change to an adopted slice use the CR delta loop (/appweaver specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta); to re-adopt from scratch, remove the feature dir first."
 
-  # 1b. Resolve this aggregate's OKF bundle concept → its source_files (the code
-  #     that IS the slice) + module dir. The INDEX adopt reverse-engineers FROM;
-  #     the code itself is the source of truth (read during authoring).
+  # 1b. Resolve the OKF concept of the aggregate this feature acts on → its source_files
+  #     + module dir. The bundle is the PROJECT's knowledge and a concept is an aggregate,
+  #     so a feature that is one capability over a shared aggregate reads the SHARED
+  #     concept, which lists every capability's code; the source-map below narrows it to
+  #     this feature's. The code itself is the source of truth (read during authoring).
   - id: concept
     action: execute_script
     script: { ref: inventory }
     subcommand: concept
-    args: ["--bundle", "{{bundle_dir}}", "--aggregate", "{{feature_name}}"]
+    args: ["--bundle", "{{bundle_dir}}", "--aggregate", "{{aggregate_primary}}"]
     outputs:
       - { name: concept_exists, from: "$.exists" }
       - { name: concept_path,   from: "$.concept_path" }
@@ -274,7 +296,7 @@ workflow:
     action: verify_context
     require_true: concept_exists
     on_false: stop
-    on_false_message: "No feature '{{feature_name}}' in the onboard feature map under {{bundle_dir}}. If you have not onboarded, run /appweaver onboard first, then use the exact feature name from {{bundle_dir}}/aggregates/index.md. If '{{feature_name}}' is a NEW feature (no existing code), do NOT adopt it — author it through the forward pipeline (/appweaver specify → plan → implement), which onboard already made brownfield-ready."
+    on_false_message: "No concept for the aggregate '{{aggregate_primary}}' — the one feature '{{feature_name}}' acts on — in the onboard bundle under {{bundle_dir}}. If its bounded context has not been onboarded, run /appweaver onboard <Context> first; {{bundle_dir}}/aggregates/index.md lists each aggregate with the features that act on it. If '{{feature_name}}' is a NEW feature (no existing code), do NOT adopt it — author it through the forward pipeline (/appweaver specify → plan → implement), which onboard already made brownfield-ready."
 
   # Governance prerequisite: the reverse steps below are authored AGAINST the project
   # onboard established (the constitution halves + guardrails/projects/<project>/ rule set).
@@ -291,6 +313,16 @@ workflow:
       - { name: gov_domain,     from: "$.domain" }
       - { name: rulemap_exists, from: "$.rulemap_exists" }
 
+  # ⌛ OPEN, now that onboard runs once per BOUNDED CONTEXT: this gate asks whether
+  # ANY context has been onboarded, and it needs to ask whether THIS FEATURE'S
+  # context has. The narrower question is already answered next door — require_concept
+  # stops when the feature has no OKF concept, and a feature only has one once its
+  # context was onboarded — so the sequence is safe today and the gap is in what the
+  # message says, not in what it lets through. Tightening it properly means resolving
+  # the feature's context from the concept's `bounded_context:` stamp and naming that
+  # context in the refusal. Related and unresolved: `fidelity_gate` is per feature and
+  # has no context-level equivalent — a context-wide one would fail a whole context on
+  # a single mismapped feature.
   - id: require_governance
     action: verify_context
     require_true: rulemap_exists
@@ -451,7 +483,7 @@ workflow:
     output_target: { type: file, path: "{{spec_file}}" }
     task: |
       Reverse-engineer the MASTER specification (the target spec.md in context)
-      for the aggregate '{{feature_name}}' FROM ITS CODE. The bundle concept (in
+      for the feature '{{feature_name}}' FROM ITS CODE. The bundle concept (in
       context) is the INDEX — its `source_files` list the code that IS this slice;
       READ those files (under {{module_dir}}, listed below) as the SOURCE OF TRUTH.
       The concept is a summary; the CODE is authoritative — if they disagree, the
@@ -459,7 +491,13 @@ workflow:
 
       Capture what the code ACTUALLY DOES, as-built (bugs/quirks included), in the
       template's vocabulary:
-      - The feature IS the aggregate; set the Aggregate field, keep US-1.
+      - THIS FEATURE ACTS ON {{aggregates_csv}}. Write exactly that on the Domain Model
+        Reference's `**Acts on aggregate(s)**:` line, each name in backticks — every later
+        command finds this feature's part of the domain model by reading that line. The
+        feature is the capability scope the developer confirmed in the boundary map,
+        whatever it is named: its user stories are that capability's operations and no
+        others. Sharing a name with an aggregate does not make it that aggregate's only
+        feature — other features may act on the same aggregate. Keep US-1.
       - Each command / endpoint / use-case the code exposes is a USER STORY (US-n),
         never a separate feature. Derive its Given/When/Then from the code's paths.
       - System Requirements in EARS (THE SYSTEM SHALL / WHEN / IF…THEN / WHILE /
@@ -501,7 +539,7 @@ workflow:
         rule the code does not exhibit. Behaviour that is clearly present is
         "(certain)".
       - Reference the source-map: note that legacy-artefact ↔ requirement links
-        live in `specs/{{feature_name}}/source-map.md` (authored next).
+        live in `{{feature_dir}}/source-map.md` (authored next).
       - This is v1.0: fill the Change History row; keep US-1's "Added: v1.0".
       - Business-facing + testable; NO implementation mechanics (an external interop
         OBLIGATION is an IC- requirement, never the adapter design).
@@ -538,20 +576,32 @@ workflow:
     output_target: { type: file, path: "{{domain_model}}" }
     task: |
       Reverse-engineer the BOUNDED CONTEXT's DOMAIN MODEL (the target domain-model.md in
-      context) for the aggregate '{{feature_name}}', FROM ITS CODE. The reversed spec (in
-      context) names the aggregate and cites the invariant ids; this document DEFINES them.
-      READ the source files listed below — the code is the SOURCE OF TRUTH.
+      context) for the aggregate(s) the feature '{{feature_name}}' acts on —
+      {{aggregates_csv}} — FROM ITS CODE. The reversed spec (in context) names them and
+      cites the invariant ids; this document DEFINES them. READ the source files listed
+      below — the code is the SOURCE OF TRUTH.
 
-      - ADD ONE `## Aggregate: <Name>` SECTION for this feature's aggregate: its boundary
+      - THE SECTION IS NAMED AFTER THE AGGREGATE, NEVER THE FEATURE: {{aggregate_sections}},
+        exactly. Every later command finds this feature's part of the model by that
+        heading. Where the feature and the aggregate share a name the two are the same
+        thing; where they differ, a section headed '{{feature_name}}' is a defect — the
+        next feature over the same aggregate would define its root a second time.
+      - IF THAT SECTION ALREADY EXISTS, another feature over the same aggregate was adopted
+        first. EXTEND it and never write a second one: add `{{feature_name}}` to its
+        `Serving specs` line, and add only what THIS feature's code evidences that the
+        section lacks — an entity, a lifecycle state, a BR-nnn numbered after the highest
+        one already there. Leave what the earlier feature wrote exactly as it is.
+      - OTHERWISE ADD ONE `## Aggregate: <Name>` SECTION per aggregate, `{{feature_name}}`
+        on its `Serving specs` line: its boundary
         (owns / references by id / out of scope), entities, value objects, domain events,
         lifecycle states, and every always-true invariant the code enforces as a stable
         BR-nnn with its RULE TEXT. The spec cites those ids and never restates them.
       - IF THE MODEL ALREADY HAS CONTENT, this is the context's SECOND (or later) adopted
-        slice. ADD this aggregate as a new section and EXTEND the ubiquitous language. Do
-        NOT rewrite, renumber or "tidy" the aggregates already there — other specs cite
-        their ids, and a renumbered BR breaks every citation silently. Add
-        `{{feature_name}}` to the `Serving specs` line of any existing aggregate this
-        slice also acts on.
+        slice. ADD any of this feature's aggregates not already there as a new section and
+        EXTEND the ubiquitous language. Do NOT rewrite, renumber or "tidy" the aggregates
+        already there — other specs cite their ids, and a renumbered BR breaks every
+        citation silently. Add `{{feature_name}}` to the `Serving specs` line of any
+        existing aggregate this slice also acts on.
       - MODEL WHAT THE CODE EXHIBITS, NOT WHAT GOOD DESIGN WOULD WANT. Classify entities
         vs value objects by whether the code gives the thing an IDENTITY; draw the
         boundary where the code actually draws it (what it loads and saves together).
@@ -670,7 +720,7 @@ workflow:
     task: |
       Reverse-engineer the FRONTEND LANE's master plan (the target frontend-plan.md
       in context — it is this project's code-derived UI plan template) for the
-      aggregate '{{feature_name}}', FROM ITS UI CODE. Fill the template; preserve its
+      feature '{{feature_name}}', FROM ITS UI CODE. Fill the template; preserve its
       section order.
 
       THE UI CODE IS THE SOURCE OF TRUTH — describe the surface AS-BUILT, quirks
@@ -718,13 +768,19 @@ workflow:
     output_target: { type: file, path: "{{feature_dir}}/source-map.md" }
     task: |
       Author the source-map sidecar (the target in context) from the template,
-      for aggregate '{{feature_name}}'. It is the SOURCE ANCHOR of the traceability
+      for the feature '{{feature_name}}'. It is the SOURCE ANCHOR of the traceability
       spine — it keeps spec.md / backend-plan.md clean while recording provenance here.
       - One row per legacy artefact in the bundle concept's `source_files` (read
         them under {{module_dir}}): map each to the spec ids (FR/BR/US/CN/DC/IC)
         and the backend-plan element (§/name) that now describe it, with CONFIDENCE
         (certain | inferred). EVERY source file MUST appear — the Fidelity gate
         checks full coverage both ways.
+      - THE CONCEPT IS THE AGGREGATE'S ('{{aggregate_primary}}') and lists every feature's
+        code on it. Where its `features:` names features besides '{{feature_name}}', a
+        file that serves ONLY one of those sibling capabilities is not this feature's:
+        record it under Unmapped / open as `sibling: <Feature>`, never as a mapped row.
+        The mapped rows ARE this feature's file list — later commands hand exactly those
+        files to their fix loops.
       - Where this slice has a UI half, its files map the same way, to the UX-/US-
         they realise and the frontend-plan.md section (§/name) that describes them —
         one spine, both lanes. UI files to map: {{ui_source_files}}
@@ -772,17 +828,24 @@ workflow:
       route it describes that the UI code does not have is a fabricated-plan, and a
       UI file with no home in the source-map is unmapped-code. Classify findings:
       - BLOCKING (structural — set ok=false if any):
-        (1) unmapped-code: a source file with NO home in the source-map;
+        (1) unmapped-code: a source file with NO home in the source-map — one recorded
+            there as `sibling: <Feature>` has a home;
         (2) fabricated-spec / fabricated-model / fabricated-plan: a spec id, model
             element or plan element with NO basis in the code (reverse-engineering must
             not invent behaviour or structure). For the MODEL specifically: an entity or
             value object the code does not have, an aggregate boundary it does not draw,
             a lifecycle state it never enters, or a BR-nnn whose rule nothing enforces.
             An anemic slice reversing as an anemic model is CORRECT, not a gap.
-      - ONLY ONE AGGREGATE SECTION IS THIS RUN'S. domain-model.md is the CONTEXT's and
-        may already carry sections from earlier adopted slices — judge ONLY the aggregate
-        '{{feature_name}}' reversed here. Do not report a sibling aggregate as unmapped
-        because this slice's code does not contain it.
+      - ONLY THIS FEATURE'S SECTIONS ARE THIS RUN'S. domain-model.md is the CONTEXT's and
+        may already carry sections from earlier adopted slices — judge ONLY
+        {{aggregate_sections}}. Do not report a sibling aggregate as unmapped because this
+        slice's code does not contain it. Where one of those sections' `Serving specs`
+        lists an EARLIER feature as well, the aggregate is shared: judge what this run
+        ADDED to it, and do not score the earlier feature's entities, states or
+        invariants as fabricated because this slice's code does not touch them.
+      - ALSO BLOCKING (fabricated-model): a `## Aggregate:` section this run created under
+        a name that is not one of {{aggregates_csv}} — most often '{{feature_name}}', the
+        feature's own name, used as if it were the aggregate's.
       - REVIEW (does NOT block ok — these are the Adopt review worklist, closed out
         of band): items marked "(inferred)"; as-built quirks the code shows but the
         spec under-states; invariants the code enforces that may be missing/weak;
@@ -804,7 +867,7 @@ workflow:
     context: ["{{spec_file}}", "{{domain_model}}", "{{backend_plan}}", "{{feature_dir}}/source-map.md"]
     output_target: { type: file, path: "{{feature_dir}}/adopt-review-report.md" }
     task: |
-      Write an Adopt Review report (the target) for aggregate '{{feature_name}}' —
+      Write an Adopt Review report (the target) for the feature '{{feature_name}}' (acting on {{aggregates_csv}}) —
       the out-of-band worklist for this reverse-engineered baseline. Markdown:
       - "# Adopt Review — {{feature_name}}" + today's date + "origin: reverse-engineered".
       - "verdict:" line — "BLOCKING ✗ · <n>" if blocking gaps exist, else "REVIEW ○ · <m> item(s)".
@@ -829,7 +892,7 @@ workflow:
     action: verify_context
     require_true: fidelity_ok
     on_false: stop
-    on_false_message: "Fidelity FAILED for {{feature_name}} — the reversed documents do not match the code (blocking gaps: {{blocking_gaps}}). See specs/{{feature_name}}/adopt-review-report.md. Fix the unmapped code / remove fabricated items (re-read the source, refine spec.md, {{domain_model}}, backend-plan.md and source-map.md), then re-run /appweaver adopt (after removing the dir) or resolve out of band. A `fabricated-model` gap means the reverse gave this slice structure its code does not have — an entity, a boundary, a lifecycle state or a BR-nnn nothing enforces; the fix is to record the domain as thin as the code really is, never to leave it flattering."
+    on_false_message: "Fidelity FAILED for {{feature_name}} — the reversed documents do not match the code (blocking gaps: {{blocking_gaps}}). See {{feature_dir}}/adopt-review-report.md. Fix the unmapped code / remove fabricated items (re-read the source, refine spec.md, {{domain_model}}, backend-plan.md and source-map.md), then re-run /appweaver adopt (after removing the dir) or resolve out of band. A `fabricated-model` gap means the reverse gave this slice structure its code does not have — an entity, a boundary, a lifecycle state or a BR-nnn nothing enforces; the fix is to record the domain as thin as the code really is, never to leave it flattering."
 
   # ═══════════ OKF CONCEPT — COMPLETE the shallow scan concept (deep reverse) ═══
   # onboard wrote this aggregate's OKF concept SHALLOW (a discovery stub — enough to pick the
@@ -854,29 +917,37 @@ workflow:
     tools: "Read,Write,Edit"
     permission_mode: acceptEdits
     task: |
-      COMPLETE the OKF aggregate concept for '{{feature_name}}' at {{concept_path}} — onboard
-      wrote it SHALLOW (a discovery stub from the whole-repo scan). The deep reverse has now
+      COMPLETE the OKF concept of the aggregate '{{aggregate_primary}}' at {{concept_path}} —
+      the aggregate this run adopted the feature '{{feature_name}}' over. onboard wrote it
+      SHALLOW (a discovery stub from the whole-repo scan). The deep reverse has now
       produced a TRUSTWORTHY spec.md + domain-model.md + backend-plan.md + source-map.md (in
       context); deepen the
       concept to match and LINK those artifacts. Follow the OKF concept template in context.
+      THE CONCEPT IS THE AGGREGATE'S, NOT THE FEATURE'S. Where its `features:` names more
+      than one feature, another feature's adopt may already have deepened it, and nothing
+      that run wrote is this run's to remove — reconcile ADDITIVELY.
       RECONCILE, do NOT rewrite:
       - DEEPEN the responsibilities + the owned entities / value objects / domain events /
         commands (user stories) / API endpoints / persistence to match the reversed spec,
         model and plan — the ENTITIES and VALUE OBJECTS come from domain-model.md, which is
         the authority on them; correct any drift the shallow scan got wrong (the deep docs
-        win).
-      - LINK the deep artifacts: add bundle links to specs/{{feature_name}}/spec.md,
+        win). A sibling capability's commands and endpoints stay where they are.
+      - LINK the deep artifacts: add bundle links to {{feature_dir}}/spec.md,
         backend-plan.md, source-map.md and the context's domain-model.md so the concept
-        points at the deep truth.
-      - Refresh `source_files` from the source-map (grouped by the code's OWN folders, per
-        OKF), and set `timestamp` to the baseline (inventory HEAD) commit time.
-      - Update frontmatter: keep `origin: reverse-engineered`; mark the concept ADOPTED /
-        deep-reversed (no longer a shallow scan stub) and stamp `generated_by: aw-spec-adopt`.
+        points at the deep truth. Keep every link another feature's adopt added.
+      - UNION `source_files` with the source-map's mapped files (grouped by the code's OWN
+        folders, per OKF) — never drop a file already listed, which may be a sibling
+        capability's — and set `timestamp` to the baseline (inventory HEAD) commit time.
+      - Update frontmatter: keep `origin: reverse-engineered`; make sure `features:`
+        includes '{{feature_name}}'; stamp `generated_by: aw-spec-adopt`; and record that
+        '{{feature_name}}' is ADOPTED / deep-reversed. Where several features act on the
+        aggregate, record WHICH of them are adopted rather than marking the whole concept
+        done — the others are still shallow.
       - Resolve any `open_questions` the deep reverse answered; keep the rest.
       - Do NOT touch the concept's Depends-On / Cross-References sections (xref_record
         maintains those next), and do NOT edit any OTHER aggregate concept.
-      Append a one-line `log.md` entry (bundle root) under today's date noting '{{feature_name}}'
-      was deep-adopted. Write ONLY {{concept_path}} (+ its dir index.md / bundle log.md if a
+      Append a one-line `log.md` entry (bundle root) under today's date noting the feature
+      '{{feature_name}}' of '{{aggregate_primary}}' was deep-adopted. Write ONLY {{concept_path}} (+ its dir index.md / bundle log.md if a
       link or description changed). Report what you deepened.
     outputs:
       - { name: concept_completed, from: "$.files" }
@@ -886,14 +957,17 @@ workflow:
   #     (its External integrations table, IC-); record them into the shared OKF bundle — a
   #     Cross-References row in every
   #     SIBLING aggregate this slice uses (their inventory concepts already exist, so this
-  #     resolves them rather than stubbing), plus this slice's own Depends-On. Same
+  #     resolves them rather than stubbing), plus the Depends-On of the aggregate this
+  #     feature acts on — the union over every feature on that aggregate, so adopting one
+  #     capability never erases another's edges. Keyed by --feature-dir so record resolves
+  #     the aggregate itself rather than being told a feature name. Same
   #     reconcile-on-write helper as forward implement, stamped origin reverse-engineered,
   #     additive to the inventory bundle. Runs only after fidelity passes.
   - id: xref_record
     action: execute_script
     script: { ref: xref }
     subcommand: record
-    args: ["--using", "{{feature_name}}", "--design", "{{backend_plan}}", "--bundle", "{{bundle_dir}}", "--origin", "reverse-engineered"]
+    args: ["--feature-dir", "{{feature_dir}}", "--design", "{{backend_plan}}", "--bundle", "{{bundle_dir}}", "--origin", "reverse-engineered"]
     outputs:
       - { name: xref_wrote,      from: "$.wrote" }
       - { name: xref_edge_count, from: "$.edge_count" }
@@ -1115,7 +1189,12 @@ outputs:
   ui_lane: "{{ui_lane}}"
   ui_count: "{{ui_count}}"
   source_map: "{{feature_dir}}/source-map.md"
-  aggregate: "{{feature_name}}"
+  feature: "{{feature_name}}"
+  # What the feature acts on. Equal to the feature on a 1:1 slice; not on a feature that
+  # is one capability over a shared aggregate. aggregate_source says which of the spec,
+  # the boundary map or the feature name answered.
+  aggregate: "{{aggregates_csv}}"
+  aggregate_source: "{{aggregate_source}}"
   source_count: "{{source_count}}"
   review_items: "{{review_items}}"
   concept_completed: "{{concept_completed}}"
@@ -1125,4 +1204,4 @@ outputs:
   composed_file: "{{composed_file}}"
   technical_reconcile_ok: "{{technical_ok}}"
   domain_reconcile_ok: "{{domain_ok}}"
-  next: "Adopted {{feature_name}} (spec.md + backend-plan.md + source-map.md, v1.0) and ADDED its aggregate section to the bounded context `{{context}}`'s shared {{domain_model}} — the spec cites BR-nnn by id, the model carries their text, so this slice is checkable by the same gates as a greenfield one and analyze-plan's check 4 now has a model to check against. Other features in this context keep their own aggregate sections untouched. COMPLETED its OKF concept (deepened + linked the deep artifacts; {{xref_edge_count}} cross-slice edge(s) recorded). UI HALF: ui_lane={{ui_lane}} — where it is true this slice also has frontend-plan.md, reversed from the {{ui_count}} UI file(s) the feature map attributes to it; where it is false the repo declared no frontend lane, or this aggregate owns no part of its surface, and a service-only adoption is the correct outcome rather than a gap. The SHARED UI surface (app shell, layout, design system) belongs to no slice and stays in {{bundle_dir}}/architecture/frontend.md. NOTE — governance reconcile is currently HELD (reconcile_governance=false): this run did NOT modify the constitution halves or the guardrails/projects/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in specs/{{feature_name}}/adopt-review-report.md out of band. The slice is now a NORMAL feature: refine via /appweaver analyze-plan, then drive every change through the CR delta loop (/appweaver specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta). If a change edits untested legacy behaviour with blast radius, characterize just that surface first (optional on-touch fence). To restore governance reconcile, set reconcile_governance to \"true\" in the workflow vars."
+  next: "Adopted {{feature_name}} (spec.md + backend-plan.md + source-map.md, v1.0) and wrote {{aggregate_sections}} — the model section(s) for the aggregate(s) it acts on, resolved from the {{aggregate_source}} — in the bounded context `{{context}}`'s shared {{domain_model}}. The spec cites BR-nnn by id, the model carries their text, so this slice is checkable by the same gates as a greenfield one and analyze-plan's check 4 now has a model to check against. A section another feature over the same aggregate wrote first was EXTENDED, never duplicated; every other section is untouched. COMPLETED the OKF concept of {{aggregate_primary}} (deepened + linked the deep artifacts; {{xref_edge_count}} cross-slice edge(s) recorded). UI HALF: ui_lane={{ui_lane}} — where it is true this slice also has frontend-plan.md, reversed from the {{ui_count}} UI file(s) the feature map attributes to it; where it is false the repo declared no frontend lane, or this aggregate owns no part of its surface, and a service-only adoption is the correct outcome rather than a gap. The SHARED UI surface (app shell, layout, design system) belongs to no slice and stays in {{bundle_dir}}/architecture/frontend.md. NOTE — governance reconcile is currently HELD (reconcile_governance=false): this run did NOT modify the constitution halves or the guardrails/projects/{{gov_domain}}/ rule set, so they keep onboard's provisional scaffold. Close any items in {{feature_dir}}/adopt-review-report.md out of band. The slice is now a NORMAL feature: refine via /appweaver analyze-plan, then drive every change through the CR delta loop (/appweaver specify → plan → analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta). If a change edits untested legacy behaviour with blast radius, characterize just that surface first (optional on-touch fence). To restore governance reconcile, set reconcile_governance to \"true\" in the workflow vars."