aw-spec-cli 0.1.31 → 0.1.33

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

@@ -10,16 +10,20 @@
 #                                                          ← you are here
 #
 # It reads back the model the greenfield sequence writes — bounded context →
-# aggregate → feature → operation — from the code: the module folder is the context,
-# a declared aggregate-root type is the aggregate, a UI features/<Feature>/ folder is
-# the capability, and a slice under the module's Features/ is one operation (a user
-# story), never a feature. Three passes; the generated document explains each to the
-# operator reading it, in the wording of the template
+# aggregate → feature → operation — from the code, whatever its stack: the module folder
+# is the context, a declared aggregate-root type is the aggregate, a UI
+# features/<Feature>/ folder is the capability, and an operation is a slice under the
+# module's Features/, a command/query handler, a use case or an endpoint (a controller
+# action, an annotated or decorated handler, a router call) — never a feature. Three
+# passes; the generated document explains each to the operator reading it, in the
+# wording of the template
 # .appweaver/templates/proposed-inventory-template.md, overridable per project:
 #   A  the aggregates. Four strategies — domain (the roots the code declares),
 #      structure, reference graph, persistence — each offered only where its
 #      evidence exists, each reporting its own numbers. Declared roots that
-#      operations act on are chosen ahead of any measured strategy.
+#      operations act on are chosen ahead of any measured strategy. A project that
+#      declares a UI lane and no service lane has one strategy, `ui`: the API
+#      resources its UI calls are the aggregates, its calls the operations.
 #   B  the operations and their seams — each operation's route, the aggregate it
 #      acts on, whether it creates one. Emits signals, never decisions.
 #   C  the features — one per UI feature folder, holding the operations it calls;
@@ -40,8 +44,8 @@
 # =============================================================================
 
 name: aw-spec-inventory
-description: Brownfield discovery — scan an existing codebase and propose its Features and Bounded Contexts, in dependency order with their dependencies, as an editable specs/proposed-inventory.md. Runs three passes (aggregate identification by a selectable evidence-gated strategy, a seam overlay over application/API/UI, and a 1:1-by-default feature proposal with evidenced splits offered but never applied). `apply` validates the operator's edits and regenerates the machine map onboard consumes. Never modifies source.
-version: 2.0.0
+description: Brownfield discovery — scan an existing codebase in any stack and propose its Features and Bounded Contexts, in dependency order with their dependencies, as an editable specs/proposed-inventory.md. Runs three passes (aggregate identification by a selectable evidence-gated strategy, a seam overlay over application/API/UI, and a 1:1-by-default feature proposal with evidenced splits offered but never applied); a project with a UI lane and no service lane is read from the API calls its UI makes. `apply` validates the operator's edits and regenerates the machine map onboard consumes. Never modifies source.
+version: 2.1.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -51,10 +55,12 @@ inputs:
       Either the literal word `apply` — validate the edited specs/proposed-inventory.md
       and regenerate the machine map — or an optional Pass A strategy name
       (domain | structure | reference | persistence) to force, plus free-text focus
-      hints. With no argument, `domain` is proposed where the code declares aggregate
-      roots that operations act on, and otherwise the highest-coverage available
-      strategy; the operator confirms it from a menu carrying each strategy's
-      measured numbers.
+      hints. A strategy named as the first word is used without asking; a first word
+      that names none forces nothing. With no strategy named, `domain` is proposed where
+      the code declares aggregate roots that operations act on, and otherwise the
+      highest-coverage available strategy; the operator confirms it from a menu carrying
+      each strategy's measured numbers, the proposed one first. A project with no
+      service lane is read by `ui` alone.
     required: false
     bind: USER_INPUT
 
@@ -73,7 +79,6 @@ standards:
 
 vars:
   mode: "propose"          # apply-mode driver
-  strategy: ""             # forced Pass A strategy; empty = probe default
   feature_count: "0"
   proposal_ok: "false"
 
@@ -142,17 +147,27 @@ workflow:
 
   # 1. WHICH LANES, AND WHERE IS THEIR SOURCE. Same declaration onboard reads:
   #    the scan is scoped to the declared subtrees so backend candidates are not
-  #    drawn from UI source and vice versa.
+  #    drawn from UI source and vice versa. A lane can be declared before it is built,
+  #    so a lane root folder that does not exist yet is allowed here: the scan reads
+  #    the lanes whose folders exist and the proposal names the one it did not read.
   - id: lane_model
     action: execute_script
     condition: "{{mode}} == propose"
     script: { ref: actions }
     subcommand: lane-verify
-    args: ["--command", "/appweaver inventory"]
+    args: ["--command", "/appweaver inventory", "--allow-missing-root"]
     outputs:
       - { name: lane_model_ok,     from: "$.ok" }
       - { name: lane_model_issues, from: "$.message" }
+      - { name: kinds_on_disk,     from: "$.kinds_on_disk" }
+      - { name: missing_roots,     from: "$.missing_roots" }
+      - { name: be_declared,       from: "$.backend_declared" }
+      - { name: be_built,          from: "$.backend_root_exists" }
+      - { name: be_lane_id,        from: "$.backend_lane_id" }
       - { name: be_root,           from: "$.backend_source_path" }
+      - { name: fe_declared,       from: "$.frontend_declared" }
+      - { name: fe_built,          from: "$.frontend_root_exists" }
+      - { name: fe_lane_id,        from: "$.frontend_lane_id" }
       - { name: fe_root,           from: "$.frontend_source_path" }
 
   - id: lane_model_gate
@@ -166,16 +181,48 @@ workflow:
       holds which lane before it starts. Run /appweaver select-stack first — it
       detects what this repo already is and lets you correct the proposal.
 
+  - id: lane_built_gate
+    action: verify_context
+    condition: "{{mode}} == propose"
+    require_non_empty: kinds_on_disk
+    on_empty: stop
+    on_empty_message: >
+      /appweaver inventory has no code to read: {{missing_roots}}
+      Inventory reads the code of the lanes whose folders exist, and no declared lane
+      has one yet.
+
+  # A declared lane with no folder yet is not read. Said once, here, and in the
+  # proposal's Scanned line; the run goes on with the lane that exists.
+  - id: be_unbuilt_warning
+    action: verify_context
+    condition: "{{be_declared}}"
+    require_true: be_built
+    on_false: continue
+    on_false_message: >
+      Service lane '{{be_lane_id}}' is declared at {{be_root}}, which does not exist
+      yet, so it is not read: the map is read from the UI lane alone.
+
+  - id: fe_unbuilt_warning
+    action: verify_context
+    condition: "{{fe_declared}}"
+    require_true: fe_built
+    on_false: continue
+    on_false_message: >
+      Frontend lane '{{fe_lane_id}}' is declared at {{fe_root}}, which does not exist
+      yet, so it is not read: features come from the service lane alone.
+
   # 2. PASS A + B + C. One deterministic call: every AVAILABLE strategy's
   #    clustering is run (cheap — the expensive half is authoring, which does not
   #    happen here), the seam overlay is laid over the chosen one, and the
-  #    proposal is written with its dependency waves.
+  #    proposal is written with its dependency waves. The request goes to it whole:
+  #    the script reads a strategy from its first word, and only when that word
+  #    names one, so focus hints alone force nothing.
   - id: propose
     action: execute_script
     condition: "{{mode}} == propose"
     script: { ref: inventory }
     subcommand: propose
-    args: ["--service-root", "{{be_root}}", "--ui-root", "{{fe_root}}", "--strategy", "{{strategy}}"]
+    args: ["--service-root", "{{be_root}}", "--ui-root", "{{fe_root}}", "--strategy", "{{USER_INPUT}}"]
     outputs:
       - { name: proposal_ok,       from: "$.ok" }
       - { name: proposal_md,       from: "$.proposal_md" }
@@ -190,6 +237,7 @@ workflow:
       - { name: split_candidates,  from: "$.split_candidates" }
       - { name: contexts_ordered,  from: "$.contexts_ordered" }
       - { name: strategy_options,  from: "$.strategy_options" }
+      - { name: forced_option,     from: "$.forced_option" }
       - { name: proposal_error,    from: "$.error" }
 
   # 2b. Substance gate. A scan with nothing to propose is the one outcome that
@@ -204,26 +252,29 @@ workflow:
     on_mismatch: stop
     on_mismatch_message: >
       /appweaver inventory found nothing to propose. {{proposal_error}}
-      Check that the service lane in .appweaver/stacks.json names the directory
-      that holds the application source (/appweaver select-stack re-declares it),
-      then re-run /appweaver inventory.
+      Check that each lane in .appweaver/stacks.json names the directory that holds
+      its source (/appweaver select-stack re-declares them), then re-run
+      /appweaver inventory.
 
   # 3. THE STRATEGY PICK. Offered from the probe, each option carrying its own
   #    measured numbers — features found, share of source covered, how many
   #    one-file candidates it produced. A strategy that would return nothing is
   #    not in the list, because choosing it would be the zero-candidate stop
-  #    arrived at deliberately. One option auto-confirms.
+  #    arrived at deliberately. One option auto-confirms. A strategy the request
+  #    named is taken without asking (`forced_option` is its option line, empty when
+  #    none was named); otherwise the proposed strategy is the first option, so a
+  #    run that cannot ask takes the proposal.
   - id: pick_strategy
     action: user_select
     condition: "{{mode}} == propose"
     prompt: >
       Pass A found these candidate aggregates. Which evidence should the map be
-      built from? (`{{chosen_strategy}}` is proposed: the roots the code declares
-      where operations act on them, otherwise the highest coverage, ties broken by
-      fewest single-file candidates. Coverage is how much code a strategy placed,
-      not whether it placed it right — compare the aggregate counts too.)
+      built from? (`{{chosen_strategy}}` is proposed and listed first: the roots the
+      code declares where operations act on them, otherwise the highest coverage, ties
+      broken by fewest single-file candidates. Coverage is how much code a strategy
+      placed, not whether it placed it right — compare the aggregate counts too.)
     options_from_variable: strategy_options
-    preselect_from: chosen_strategy
+    preselect_from: forced_option
     single_option_confirm: true
     outputs:
       - { name: picked, from: selection }

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

@@ -112,9 +112,11 @@
 # generated, which subtrees are scanned, and what technology the derived rules name.
 # select-stack detects all three from the repo's own files and proposes them, so answering
 # it on an existing codebase is mostly confirmation — but it is a person's confirmation,
-# which is exactly what detection on a legacy repo needs. A declared lane root folder that is
-# not a directory stops this run with the fix named rather than producing a scaffold
-# reverse-engineered from nothing.
+# which is exactly what detection on a legacy repo needs. A lane can be declared before
+# it is built: a declared lane whose lane root folder does not exist yet is governed as
+# absent for this run, with a warning naming it, and its governance is left to the
+# developer. When no declared lane's folder exists the run stops, rather than producing a
+# scaffold reverse-engineered from nothing.
 #
 # WHICH LANES EXIST is therefore the DECLARATION's answer, and it answers in both
 # directions — a project that declared `(none)` for the UI lane gets no UI half, no
@@ -149,8 +151,8 @@
 # =============================================================================
 
 name: aw-spec-onboard
-description: Onboard an existing codebase for brownfield DEVELOPMENT — a deterministic whole-repo scan produces a high-level OKF feature map (folders/concepts) PLUS the project-level governance scaffold (split constitution + guardrails/brf-<domain>/ with its DOMAIN rule files at domain/ + domain-rule-bindings + code-derived TECHNICAL rule files at service/ + tech-rule-bindings + activated domain), all provisional-from-scan. The first context authors that tier; every later context amends it additively from its own code (new rules, principles and map entries — never a rewrite, renumbering or deletion; a contradiction is recorded as a Divergence note), and a tier that does not exist yet, such as a lane declared after an earlier onboard, is authored in full. Naming an already-onboarded context re-runs that governance pass alone. Where the scan finds a frontend lane in the CODE, it also authors that lane's half — constitution.ui.md (UX-*) — and its code-derived rule files at brf-<domain>/frontend/, mapped under `## /aw-spec-ui-constitution`, `## /aw-spec-plan-frontend` and `## /aw-spec-implement-frontend`; a backend-only repo gets none of it. Every rule tier is reverse-engineered from the CODE alone (never a greenfield rule file), evidenced-only, and WIRED per-workflow so the whole forward pipeline AND adopt govern against THIS codebase — never a greenfield fallback. It also reverse-engineers the repo's own technical structure into a project-specific design + delta-design template pair, installed as the project template overrides, and — where the lane exists — the frontend lane's own pair from the UI source. Every authoring step is shaped by a NEUTRAL rev-templates skeleton; no greenfield constitution, rule file or document template is ever placed in context. Accepts an optional concerns list to look for (onboard decides which are actually present). Reads any declared lane, never writes one. No migration content; never modifies source.
-version: 2.3.0
+description: Onboard an existing codebase for brownfield DEVELOPMENT — a deterministic whole-repo scan produces a high-level OKF feature map (folders/concepts) PLUS the project-level governance scaffold (split constitution + guardrails/brf-<domain>/ with its DOMAIN rule files at domain/ + domain-rule-bindings + code-derived TECHNICAL rule files at service/ + tech-rule-bindings + activated domain), all provisional-from-scan. The first context authors that tier; every later context amends it additively from its own code (new rules, principles and map entries — never a rewrite, renumbering or deletion; a contradiction is recorded as a Divergence note), and a tier that does not exist yet, such as a lane declared after an earlier onboard, is authored in full. Naming an already-onboarded context re-runs that governance pass alone. Where the scan finds a frontend lane in the CODE, it also authors that lane's half — constitution.ui.md (UX-*) — and its code-derived rule files at brf-<domain>/frontend/, mapped under `## /aw-spec-ui-constitution`, `## /aw-spec-plan-frontend` and `## /aw-spec-implement-frontend`; a backend-only repo gets none of it. Every rule tier is reverse-engineered from the CODE alone (never a greenfield rule file), evidenced-only, and WIRED per-workflow so the whole forward pipeline AND adopt govern against THIS codebase — never a greenfield fallback. It also reverse-engineers the repo's own technical structure into a project-specific design + delta-design template pair, installed as the project template overrides, and — where the lane exists — the frontend lane's own pair from the UI source. Every authoring step is shaped by a NEUTRAL rev-templates skeleton; no greenfield constitution, rule file or document template is ever placed in context. Accepts an optional concerns list to look for (onboard decides which are actually present). Reads any declared lane whose folder exists, never writes one; a lane declared before it is built is governed as absent and its governance left to the developer. No migration content; never modifies source.
+version: 2.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -189,7 +191,7 @@ standards:
 vars:
   # The provenance stamp every generated file carries. It names THIS workflow's version,
   # so it moves with `version:` above — one value, never a literal repeated per prompt.
-  generated_by:   "aw-spec-onboard/2.3.0"
+  generated_by:   "aw-spec-onboard/2.5.0"
   bundle_present: "false"   # set by the scan (the bundle holds concepts); reported, gates nothing
   conformant:     "false"   # OKF conformance-gate driver
   pack_present:   "false"   # the project tier exists ⇒ repo_gov, so this context AMENDS it
@@ -241,24 +243,29 @@ workflow:
   #    what to scan), and what each lane's stack is (so the derived rules name the
   #    right technology).
   #
-  #    The on-disk check is ON here, unlike in constitution: this run is about to READ
-  #    those directories. A declared lane root folder that is not there stops the run with the fix
-  #    named, rather than producing a governance scaffold reverse-engineered from
-  #    nothing.
+  #    This run is about to READ those directories, so it needs at least one to exist.
+  #    A lane can be declared before it is built, so a lane root folder that does not
+  #    exist yet is allowed here: that lane is governed as absent below, and the scan
+  #    reads the lanes whose folders exist. When none exists the run stops rather than
+  #    producing a governance scaffold reverse-engineered from nothing.
   - id: lane_model
     action: execute_script
     script: { ref: actions }
     subcommand: lane-verify
-    args: ["--command", "/appweaver onboard"]
+    args: ["--command", "/appweaver onboard", "--allow-missing-root"]
     outputs:
       - { name: lane_model_ok,     from: "$.ok" }
       - { name: lane_model_issues, from: "$.message" }
       - { name: lane_kinds,        from: "$.kinds" }
+      - { name: kinds_on_disk,     from: "$.kinds_on_disk" }
+      - { name: missing_roots,     from: "$.missing_roots" }
       - { name: be_declared,       from: "$.backend_declared" }
+      - { name: be_built,          from: "$.backend_root_exists" }
       - { name: be_lane_id,        from: "$.backend_lane_id" }
       - { name: be_profile,        from: "$.backend_profile" }
       - { name: be_root,           from: "$.backend_source_path" }
       - { name: fe_declared,       from: "$.frontend_declared" }
+      - { name: fe_built,          from: "$.frontend_root_exists" }
       - { name: fe_lane_id,        from: "$.frontend_lane_id" }
       - { name: fe_profile,        from: "$.frontend_profile" }
       - { name: fe_root,           from: "$.frontend_source_path" }
@@ -283,13 +290,24 @@ workflow:
       nor a UI lane, so onboard has no source to reverse-engineer. Re-run
       /appweaver select-stack and declare at least one lane.
 
+  - id: lane_built_gate
+    action: verify_context
+    require_non_empty: kinds_on_disk
+    on_empty: stop
+    on_empty_message: >
+      /appweaver onboard has no code to reverse-engineer: {{missing_roots}}
+      onboard derives governance from the code of the lanes whose folders exist, and
+      no declared lane has one yet.
+
   # 1. DETERMINISTIC scan of the current codebase → JSON substrate (files, churn,
   #    categories, aggregate_signals = candidate feature roots), and reports whether
   #    a bundle already holds curation.
   #
   #    SCOPED BY THE DECLARATION. Backend signals come from outside the UI lane's
   #    subtree (and inside the service lane's); frontend signals come from the UI
-  #    lane's subtree alone. This substrate is inlined verbatim into every agent
+  #    lane's subtree alone. A project with a UI lane and no service lane has no backend
+  #    signals: its candidates are the API resources the UI calls, the same reading
+  #    inventory proposed the map from. This substrate is inlined verbatim into every agent
   #    request this run makes, so an unscoped scan puts the whole frontend file list in
   #    front of the step deriving the SERVICE rules and every backend aggregate in front
   #    of the steps deriving the UI's — while each prompt tells the model to ignore what
@@ -314,11 +332,13 @@ workflow:
       - { name: bundle_dir,       from: "$.bundle_dir" }
       - { name: bundle_present,   from: "$.bundle_present" }
       - { name: bundle_md_count,  from: "$.bundle_md_count" }
-      # The frontend lane, as the CODE evidences it. `frontend_present` is true only
+      # The frontend lane, as the CODE evidences it. `frontend_evidenced` is true only
       # where a candidate root reached lane strength (a frontend build config, or a
       # real set of component/view files) — loose scripts and stylesheets under a
-      # wwwroot/ are reported in the substrate but are NOT a lane.
-      - { name: frontend_present,   from: "$.frontend_present" }
+      # wwwroot/ are reported in the substrate but are NOT a lane. It is the code's
+      # answer, kept apart from `frontend_present` (the UI rule tier exists, from
+      # pack_setup); which lanes this run governs is the declaration's answer, ui_lane.
+      - { name: frontend_evidenced, from: "$.frontend_present" }
       - { name: frontend_separable, from: "$.frontend_separable" }
       - { name: frontend_roots,     from: "$.frontend_roots" }
       - { name: frontend_root_count, from: "$.frontend_root_count" }
@@ -335,13 +355,6 @@ workflow:
       - { name: scoped_service_root, from: "$.declared_service_root" }
       - { name: scoped_ui_root,      from: "$.declared_ui_root" }
 
-  # 1b. Substance gate: no candidate features → nothing to map.
-  - id: require_aggregates
-    action: verify_context
-    require_true: aggregate_count
-    on_false: stop
-    on_false_message: "Scan found no candidate features in {{root}} (file_count={{file_count}}). Point /appweaver onboard at a codebase with a recognizable domain/vertical-slice layout, or scan a subtree that contains one."
-
   # 1c. WHICH BOUNDED CONTEXT, AND IS IT THIS ONE'S TURN. onboard runs once per
   #     context, so before anything is written it reads the map inventory
   #     produced and asks four questions: is this a context the map knows, what
@@ -494,13 +507,15 @@ workflow:
   #     The declaration selects the subtree; it never supplies a word of the governance.
   # No service lane ⇒ the technical lint loop has nothing to check, so its guard is
   # satisfied rather than left at its "not yet verified" default; a declared lane
-  # restores it, because that half does get authored and does get linted.
+  # restores it, because that half does get authored and does get linted. A lane is
+  # governed when it is declared AND its lane root folder exists: one declared before it
+  # is built has no code to reverse-engineer, so it is governed as absent.
   - id: svc_lane_absent
     action: set
     vars: { svc_lane: "false", technical_ok: "true", setup_tech_flag: "--no-technical" }
   - id: svc_lane_declared
     action: set
-    condition: "{{be_declared}}"
+    condition: "{{be_built}}"
     vars: { svc_lane: "true", technical_ok: "false", setup_tech_flag: "" }
 
   # A repo with no service lane. Rare in brownfield and real — a static site, a
@@ -510,7 +525,7 @@ workflow:
   # someone to notice that guardrails/<p>/service/ is empty.
   - id: svc_lane_warning
     action: verify_context
-    require_true: svc_lane
+    require_true: be_declared
     on_false: continue
     on_false_message: >
       No service lane in .appweaver/stacks.json — skipping the TECHNICAL constitution
@@ -521,24 +536,62 @@ workflow:
       this repo does have backend source, run /appweaver select-stack, declare it and
       re-run onboard.
 
+  # A service lane declared before it is built — a new service planned beside a front end
+  # that exists. Its governance is the developer's to provide before the forward
+  # pipeline builds it; this run authors none of it.
+  - id: svc_lane_unbuilt_warning
+    action: verify_context
+    condition: "{{be_declared}}"
+    require_true: be_built
+    on_false: continue
+    on_false_message: >
+      Service lane '{{be_lane_id}}' ({{be_profile}}) is declared at {{be_root}}, which
+      does not exist yet, so there is no service code to reverse-engineer. This run
+      authors none of the service lane's governance — the TECHNICAL constitution half,
+      the service rule set and the service design/delta-design template overrides.
+      Provide them before building the lane through the forward pipeline. Once the lane
+      has code, naming an onboarded context (/appweaver onboard <Context>) reverse-engineers
+      them from it instead.
+
   - id: ui_lane_absent
     action: set
     vars:
       ui_lane: "false"
       ui_evidence: ""
       ui_declaration_note: "no frontend lane is declared in .appweaver/stacks.json — this repo is governed as backend-only"
-  - id: ui_lane_declared
+  - id: ui_lane_unbuilt
     action: set
     condition: "{{fe_declared}}"
+    vars:
+      ui_declaration_note: "lane '{{fe_lane_id}}' ({{fe_profile}}) is declared at {{fe_root}}, which does not exist yet — no UI governance was authored for it"
+  - id: ui_lane_declared
+    action: set
+    condition: "{{fe_built}}"
     vars:
       ui_lane: "true"
       ui_evidence: "lane '{{fe_lane_id}}' ({{fe_profile}}) is declared at the lane root folder {{fe_root}}; the scan found UI source there — {{frontend_roots}}"
       ui_declaration_note: "lane '{{fe_lane_id}}' ({{fe_profile}}) at {{fe_root}} — the declared lane root folder this run reverse-engineered the UI governance out of"
 
+  # A frontend lane declared before it is built — a new front end planned beside a
+  # service that exists. Its governance is the developer's to provide before the forward
+  # pipeline builds it; this run authors none of it.
+  - id: ui_lane_unbuilt_warning
+    action: verify_context
+    condition: "{{fe_declared}}"
+    require_true: fe_built
+    on_false: continue
+    on_false_message: >
+      Frontend lane '{{fe_lane_id}}' ({{fe_profile}}) is declared at {{fe_root}}, which
+      does not exist yet, so there is no UI code to reverse-engineer. This run authors
+      none of the frontend lane's governance — constitution.ui.md, the frontend rule set
+      and the UI design/delta-design template overrides. Provide them before building the
+      lane through the forward pipeline. Once the lane has code, naming an onboarded
+      context (/appweaver onboard <Context>) reverse-engineers them from it instead.
+
   # A declared UI lane whose lane root folder holds nothing a scan recognises as UI. The
-  # path exists — lane-verify already refused the run otherwise — so this is not a
-  # broken declaration, it is an empty one: a lane scaffolded but not yet built, or a
-  # lane root folder one directory too high. Announce and continue rather than stop: the
+  # path exists — a lane whose folder does not is governed as absent above — so this is
+  # not a broken declaration, it is an empty one: a lane scaffolded but not yet built, or
+  # a lane root folder one directory too high. Announce and continue rather than stop: the
   # declaration is a person's statement and is left exactly as it stands, but the UI
   # governance below will be thin, and it is better to say why now than to let someone
   # discover a UX base derived from an empty directory.
@@ -706,6 +759,9 @@ workflow:
         confirm those against what the file actually is and move or drop one it got wrong. Keep the key and leave it EMPTY where the
         aggregate has no UI (and on a backend-only repo, where every concept has none);
         never fold these paths into `source_files`, which stays the service surface.
+        Where the aggregate signals' `strategy` is `ui` (a project with no service
+        lane), every file a signal lists is the UI lane's, its `api_files` included: list
+        them all under `ui_source_files` and leave `source_files` empty.
       - `aggregates/index.md` — the BOUNDED-CONTEXT / feature map (no frontmatter beyond
         OKF index rules). Group the links under a `## <BoundedContext>` heading per
         context, so the file shows which aggregates belong to which context rather than one
@@ -2249,6 +2305,16 @@ workflow:
         signature form + the ports/contracts. Keep exactly one subsection whose heading
         contains the word "Integration" (the External Integrations table — one port/adapter row
         per IC-): aw-xref matches it by keyword, so it is pinned regardless of layout.
+      - THE PUBLISHED SURFACE IS A PINNED FORM. In the §2 axis this project publishes its
+        endpoints from (titled with the project's own name for it), keep the skeleton's
+        endpoint block exactly — the heading `#### `[VERB] [/route]` — [purpose] · Serves …`,
+        then **Operation id**, Auth, Request, Success, the Errors table and Maps to — and the
+        `#### Requests from the frontend lane` table after the blocks. The contract scripts
+        read exactly this form: the API draft is written from the headings and the request
+        ledger between the lanes reads the operation ids and the table, so endpoints listed
+        in a table instead leave both empty. Keep the Operation id comment: an endpoint the
+        code already serves keeps the id it publishes, `—` with a §5 DA-n where it publishes
+        none, never an invented one. Omit both only where the code publishes no endpoint.
       - §3 Cross-Cutting Concerns — one row per concern THIS project's governance carries, read
         from the technical constitution (Serves = a spec id or a §5 DA-n). Do not import a
         standard concern list the constitution does not evidence.
@@ -2307,9 +2373,14 @@ workflow:
       the generated master template. Never name a layering — neither one you know nor one the
       master did not derive.
       - CARRY OVER the neutral parts of rev-templates/delta-design-template.skeleton.md (in
-        context): Change summary, Cross-section impact, Regression targets, New assumptions/
-        deviations (DA-n / WA-n), On merge — word for word: finalize-delta merges the spec and
-        the model, never this plan, which `plan main` re-derives. Keep behaviour technology-agnostic (signatures +
+        context): Change summary, Model changes this plan realises, Depends on, Cross-section
+        impact, Contract deltas for the frontend lane, Other open deltas, Regression targets,
+        New assumptions/deviations (DA-n / WA-n), On merge — word for word: finalize-delta
+        merges the spec and the model, never this plan, which `plan main` re-derives. Keep
+        the contract table's Operation id and Change columns and its added / changed /
+        removed values: analyze-plan-delta reads them to warn when a change alters or
+        removes an operation the frontend binds to. Omit that section only where the code
+        has no frontend lane. Keep behaviour technology-agnostic (signatures +
         contracts, no code); a shared element is MODIFIED in place, never duplicated; every
         changed element serves a spec id.
       - This aligns with the delta-plan module, which classifies "per the master's OWN
@@ -2656,4 +2727,4 @@ outputs:
   amended_domain_files: "{{amended_domain_files}}"
   amended_service_files: "{{amended_service_files}}"
   amended_ui_files: "{{amended_ui_files}}"
-  next: "Onboarded bounded context {{bc}} ({{bc_feature_count}} feature(s): {{bc_features}}). Its aggregate concepts ({{bc_aggregates}}) are in {{bundle_dir}}, each keyed `bounded_context: {{bc}}` and listing the features that act on it — the bundle is the project's knowledge, one concept per aggregate, never one per feature — and its specs tree now exists at {{bc_dir}}/ with a directory per feature ({{feature_dirs}}) — EMPTY on purpose: the directory says the feature is known, and the documents that describe it are written per feature by /appweaver adopt and per context by /appweaver specify. {{bc}} is now the ACTIVE bounded context (.appweaver/context.json), so /appweaver select-feature lists exactly these features and nothing from a neighbouring context; switch with /appweaver select-bounded-context. ONBOARD RUNS ONCE PER CONTEXT: contexts already done — {{onboarded_contexts}}; still open — {{remaining_contexts}}; the order the map gives is {{contexts_ordered}}. Run /appweaver onboard <NextContext> for each remaining one, or with no argument to take the next one automatically. GOVERNANCE — {{gov_mode}}. The project tier is the PROVISIONAL governance scaffold — the split constitution, the domain rule set at guardrails/{{domain_slug}}/domain/*.domain.md + domain-rule-bindings.md, each declared LANE's rule set and constitution half, the activated domain {{active_domain}}, and the code-derived design / delta-design / domain-model template overrides in .appweaver/templates/overrides/. The first context authors it; every later context AMENDS it from its own code, additively — rules, principles and map entries its code evidences, never a rewrite, renumbering or deletion of what an earlier context wrote — and a lane tier that did not exist yet is authored in full. Files this run amended — domain: {{amended_domain_files}}; service: {{amended_service_files}}; frontend: {{amended_ui_files}}. Search them for `Divergence ({{bc}})`: each marks a rule this context's code contradicts, left as written for you to decide with /appweaver constitution, which is also how you amend the tier by hand. The templates are written once per lane and never amended. To re-run this governance pass later — after declaring a lane with /appweaver select-stack, say — name an onboarded context: /appweaver onboard <Context>. ONE HALF AND ONE RULE SET PER LANE: service_lane / ui_lane report which lanes .appweaver/stacks.json declared, and the declaration is what decided. A lane declared (none) in select-stack gets none of it, which is the correct outcome and not an omission. LANE DECLARATION: read, never written — select-stack is its sole writer, and this run scanned the lane root folders it named (scanned_service_root / scanned_ui_root); scanned_backend_files / scanned_ui_files report each. ui_source_evidence_found false means the declared lane root folder of the UI lane held nothing a scan recognises as UI, so its governance is thin — move the lane root folder with /appweaver select-stack and re-run. The build/test/run commands on each lane are that PROFILE's defaults and may not match a legacy layout — review them. Because the domain is activated, resolve-domain + resolve-tech route the WHOLE forward pipeline to these code-derived rules — never another project's rules as a fallback. THE BOUNDARIES CAME FROM THE MAP, not from this run: /appweaver inventory proposed them and you confirmed them in specs/proposed-inventory.md. To change a boundary, edit that file and run /appweaver inventory apply — a context whose concepts already exist is not re-mapped; naming it re-runs only its governance pass. Develop an EXISTING feature just-in-time: /appweaver adopt <Feature> reverse-engineers its spec.md + backend-plan.md + source-map.md and deepens the OKF concept of the aggregate it acts on. Develop a NEW feature straight through the forward pipeline — /appweaver select-feature FIRST (specify and every stage after it read the active feature and STOP without one), then specify → plan → analyze-plan → implement → build → analyze-slice → run. 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), and re-derive the master plans after it with /appweaver plan main → analyze-plan — finalize-delta merges a change into spec.md and domain-model.md, never into the plans. If a validation_ok is false, its constitution half needs a manual touch (see its Sync Impact Report)."
+  next: "Onboarded bounded context {{bc}} ({{bc_feature_count}} feature(s): {{bc_features}}). Its aggregate concepts ({{bc_aggregates}}) are in {{bundle_dir}}, each keyed `bounded_context: {{bc}}` and listing the features that act on it — the bundle is the project's knowledge, one concept per aggregate, never one per feature — and its specs tree now exists at {{bc_dir}}/ with a directory per feature ({{feature_dirs}}) — EMPTY on purpose: the directory says the feature is known, and the documents that describe it are written per feature by /appweaver adopt and per context by /appweaver specify. {{bc}} is now the ACTIVE bounded context (.appweaver/context.json), so /appweaver select-feature lists exactly these features and nothing from a neighbouring context; switch with /appweaver select-bounded-context. ONBOARD RUNS ONCE PER CONTEXT: contexts already done — {{onboarded_contexts}}; still open — {{remaining_contexts}}; the order the map gives is {{contexts_ordered}}. Run /appweaver onboard <NextContext> for each remaining one, or with no argument to take the next one automatically. GOVERNANCE — {{gov_mode}}. The project tier is the PROVISIONAL governance scaffold — the split constitution, the domain rule set at guardrails/{{domain_slug}}/domain/*.domain.md + domain-rule-bindings.md, each declared LANE's rule set and constitution half, the activated domain {{active_domain}}, and the code-derived design / delta-design / domain-model template overrides in .appweaver/templates/overrides/. The first context authors it; every later context AMENDS it from its own code, additively — rules, principles and map entries its code evidences, never a rewrite, renumbering or deletion of what an earlier context wrote — and a lane tier that did not exist yet is authored in full. Files this run amended — domain: {{amended_domain_files}}; service: {{amended_service_files}}; frontend: {{amended_ui_files}}. Search them for `Divergence ({{bc}})`: each marks a rule this context's code contradicts, left as written for you to decide with /appweaver constitution, which is also how you amend the tier by hand. The templates are written once per lane and never amended. To re-run this governance pass later — after declaring a lane with /appweaver select-stack, say — name an onboarded context: /appweaver onboard <Context>. ONE HALF AND ONE RULE SET PER LANE: service_lane / ui_lane report which lanes this run governed — each lane .appweaver/stacks.json declares whose lane root folder exists. A lane declared (none) in select-stack gets none of it, which is the correct outcome and not an omission, and so does a lane whose folder does not exist yet: its governance is yours to provide before the forward pipeline builds it. LANE DECLARATION: read, never written — select-stack is its sole writer, and this run scanned the lane root folders it named (scanned_service_root / scanned_ui_root); scanned_backend_files / scanned_ui_files report each. ui_source_evidence_found false means the declared lane root folder of the UI lane held nothing a scan recognises as UI, so its governance is thin — move the lane root folder with /appweaver select-stack and re-run. The build/test/run commands on each lane are that PROFILE's defaults and may not match a legacy layout — review them. Because the domain is activated, resolve-domain + resolve-tech route the WHOLE forward pipeline to these code-derived rules — never another project's rules as a fallback. THE BOUNDARIES CAME FROM THE MAP, not from this run: /appweaver inventory proposed them and you confirmed them in specs/proposed-inventory.md. To change a boundary, edit that file and run /appweaver inventory apply — a context whose concepts already exist is not re-mapped; naming it re-runs only its governance pass. Develop an EXISTING feature just-in-time: /appweaver adopt <Feature> reverse-engineers its spec.md + backend-plan.md + source-map.md and deepens the OKF concept of the aggregate it acts on. Develop a NEW feature straight through the forward pipeline — /appweaver select-feature FIRST (specify and every stage after it read the active feature and STOP without one), then specify → plan → analyze-plan → implement → build → analyze-slice → run. 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), and re-derive the master plans after it with /appweaver plan main → analyze-plan — finalize-delta merges a change into spec.md and domain-model.md, never into the plans. If a validation_ok is false, its constitution half needs a manual touch (see its Sync Impact Report)."

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

@@ -117,7 +117,7 @@
 
 name: aw-spec-plan
 description: "Author the feature's lane plans from the spec and the bounded context's domain model — backend-plan.md when a backend lane is declared, frontend-plan.md when a frontend lane is, both when both are. Lanes come from .appweaver/stacks.json, so one command covers backend-only, frontend-only and full-stack projects; the former separate design-ui command is folded in. It ASKS what it is planning, the way implement asks what it is building: the master (`main`), one of the OPEN CHANGES, or a new plan-only change for a refactor with no spec delta — the argument doubles as the answer, and the menu appears only once a master exists, so a first run bootstraps with no prompt. `main` on a feature that already has masters RE-DERIVES them from the merged spec.md + domain-model.md — the operation finalize-delta's contract assumes when it merges a change's spec and model halves and no lane plan — and is confirmed before it rewrites anything. A change instead gets delta-backend-plan.md / delta-frontend-plan.md inside changes/<CR-id>/ while the masters stay untouched, written against the effective model (the master model, the change's own model delta, and the pending model deltas of LOWER waves, which are its predecessors) and against the feature's real source files from its OKF concept. Master authoring is template-driven: the kit's templates by default, or the code-derived as-built structure when onboard installed an override. Authoring only — a master gates at analyze-plan; a change ships through the CR chain."
-version: 5.5.0
+version: 5.5.1
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -880,7 +880,11 @@ workflow:
       - NAME EVERY ENDPOINT with its route, verb and operation id — its name in the
         service's published API document, unique across the service. Where the code
         already gives the endpoint one, record THAT id exactly as the code spells it; the
-        frontend plan cites it and implement finds the endpoint by it.
+        frontend plan cites it and implement finds the endpoint by it. An endpoint the code
+        already serves under no id keeps `—`, with a §5 DA-n saying so — never an invented
+        id. Write each endpoint as the template's endpoint block — the heading
+        `#### `VERB /route` — …` with its **Operation id** field — never as a row in a table
+        of endpoints: the API draft and the request ledger between the lanes read that form.
       - ANSWER THE FRONTEND LANE'S CONTRACT REQUESTS. Still open in the frontend plan's
         "Contract deltas needed" table: {{req_backend_text}}. Answer each one in a
         "Requests from the frontend lane" table beside this feature's endpoints (| Request

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

@@ -16,7 +16,10 @@
 # still READ the other lane where they need it: a frontend plan binds to the backend
 # plan's published surface, which the backend developer owns. specify, finalize-delta and
 # close-delta do NOT follow it: the spec is written whole, from its rules and standards,
-# and a change merges and closes with whatever its lanes have delivered.
+# and a change merges and closes with whatever its lanes have delivered. Brownfield adopt
+# does not follow it either: it reverses a feature once, every half its code has, because
+# it cannot run a second time for the other lane, so the other lane's developer finds
+# their plan already written.
 #
 # THE OPTIONS COME FROM stacks.json. Both lanes declared → backend, frontend and both.
 # One lane declared → that lane only, picked without a question (there is nothing to
@@ -32,8 +35,8 @@
 # =============================================================================
 
 name: aw-spec-select-lane
-description: Choose the lane this developer works on — backend, frontend or both — and store it in .appweaver/lane.json, which is not committed, so each developer keeps their own. The options come from the stacks declared in .appweaver/stacks.json, all three when both lanes are declared and only the declared one otherwise. plan, analyze-plan, implement, build and analyze-slice then write only that lane while still reading the other; specify, finalize-delta and close-delta do not follow it. select-stack writes the default (every declared lane); run this to narrow it.
-version: 1.0.0
+description: Choose the lane this developer works on — backend, frontend or both — and store it in .appweaver/lane.json, which is not committed, so each developer keeps their own. The options come from the stacks declared in .appweaver/stacks.json, all three when both lanes are declared and only the declared one otherwise. plan, analyze-plan, implement, build and analyze-slice then write only that lane while still reading the other; specify, finalize-delta, close-delta and brownfield adopt do not follow it. select-stack writes the default (every declared lane); run this to narrow it.
+version: 1.0.1
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -100,5 +103,5 @@ outputs:
   working_lane: "{{working_lane}}"
   working_kinds: "{{working_kinds}}"
   lane_file: "{{lane_file}}"
-  note: "Working lane `{{working_lane}}` stored in {{lane_file}}. The file is not committed — it is this developer's choice, and another developer on the same repository keeps their own. From now on plan, analyze-plan, implement, build and analyze-slice write only the working lane: they plan it, gate it with its own receipt, generate it, compile it and test it. They still READ the other lane where they need it — a frontend plan binds to the operation ids the backend plan publishes. specify writes the whole spec whatever lane is chosen, and finalize-delta and close-delta merge and close a change with whatever its lanes have delivered. Re-running /appweaver select-stack resets the working lane to every declared lane."
+  note: "Working lane `{{working_lane}}` stored in {{lane_file}}. The file is not committed — it is this developer's choice, and another developer on the same repository keeps their own. From now on plan, analyze-plan, implement, build and analyze-slice write only the working lane: they plan it, gate it with its own receipt, generate it, compile it and test it. They still READ the other lane where they need it — a frontend plan binds to the operation ids the backend plan publishes. specify writes the whole spec whatever lane is chosen, and finalize-delta and close-delta merge and close a change with whatever its lanes have delivered. Brownfield adopt reverses a feature once, every half its code has, whatever lane is chosen, so the other lane's developer finds their plan already written. Re-running /appweaver select-stack resets the working lane to every declared lane."
   next: "Run the lane's flow on the active feature: /appweaver plan → analyze-plan → implement → build → analyze-slice. Switch lanes any time with /appweaver select-lane backend | frontend | both."

package/assets/.appweaver/scripts/powershell/aw-inventory.ps1

@@ -3,17 +3,19 @@
 # The brownfield inventory logic lives ONCE in ../python/aw-inventory.py (a
 # faithful cross-platform port of Reference/okf-inventory.sh + aggregate-root
 # signals). This wrapper exists only so the orchestrator's execute_script,
-# which dispatches sh:/ps1: variants, can invoke it. All args (subcommand +
-# options) pass straight through.
+# which dispatches sh:/ps1: variants, can invoke it. Args pass through, each flag
+# joined to its value (see below).
 #
 #   aw-inventory.ps1 scan     [--root <dir>] [--out <path>] [--bundle <dir>] [--config <yml>]
 #                             [--service-root <p>] [--ui-root <p>]   (the declared lane paths:
 #                             backend signals come from outside the UI subtree, frontend
 #                             signals from inside it, so neither carries the other's files)
 #   aw-inventory.ps1 propose  [--root <dir>] [--service-root <p>] [--ui-root <p>]
-#                             [--strategy structure|reference|persistence] [--out <md>] [--map <json>]
+#                             [--strategy domain|structure|reference|persistence|ui]
+#                             [--out <md>] [--map <json>]
 #                             (Pass A+B+C: writes the editable specs/proposed-inventory.md
-#                             and the machine map onboard reads)
+#                             and the machine map onboard reads; with a UI lane and no
+#                             service lane the map is read from the UI lane, strategy `ui`)
 #   aw-inventory.ps1 apply    [--root <dir>] [--proposal <md>] [--map <json>]
 #                             (validates the operator's edits to the proposal and
 #                             regenerates the machine map; reports the row it cannot resolve)
@@ -28,5 +30,18 @@
 #   aw-inventory.ps1 validate --bundle <dir> [--repo-root <dir>]
 $ErrorActionPreference = "Stop"
 $core = Join-Path $PSScriptRoot "..\python\aw-inventory.py"
-& python3 $core @args
+# Each value travels to python as ONE `--flag=value` argument. Windows PowerShell 5.1, and
+# pwsh before 7.3, drop an empty argument when calling a program, which would leave a flag
+# such as --service-root (empty in a project with no service lane) or --strategy (empty on
+# a first run) with the next flag as its value, or with none. Every flag here takes a value.
+$fwd = @()
+for ($i = 0; $i -lt $args.Count; $i++) {
+    $a = "$($args[$i])"
+    if ($a.StartsWith('--') -and -not $a.Contains('=') -and $i + 1 -lt $args.Count) {
+        $fwd += ($a + '=' + $args[++$i])
+    } else {
+        $fwd += $a
+    }
+}
+& python3 $core @fwd
 exit $LASTEXITCODE