aw-spec-cli 0.1.27 → 0.1.28

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

@@ -78,8 +78,8 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
 - **Domain rule files: NEVER.** Domain reaches plan solely as spec ids and the context's
   `domain-model.md`.
 - **Technical rule files: yes** — the architecture and cross-cutting rules each lane's plan
-  mediates the spec against: `## /aw-spec-plan` for the service lane, `## /aw-spec-plan-ui`
-  for the frontend lane.
+  mediates the spec against: `## /aw-spec-plan-backend` for the service lane,
+  `## /aw-spec-plan-frontend` for the frontend lane.
 - Constitution: the **technical** half in the service lane, the **UI** half in the frontend one.
 
 ### `implement` — *code generation, both lanes, both paths*
@@ -91,10 +91,9 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
   `domain-model.<CR-id>.delta.md` joins it, since the master is not merged until
   finalize-delta. The model is READ, never mined for work: what it holds and no plan element
   realises is a planning gap, not code to invent.
-- **Technical rule files: yes** — the code-generation and convention set, keyed per lane and,
-  for the service lane, per path: `## /aw-spec-implement` generating a master plan,
-  `## /aw-spec-implement-delta` generating a change's delta plan, `## /aw-spec-implement-ui`
-  for the frontend lane either way.
+- **Technical rule files: yes** — the code-generation and convention set, keyed per lane, the
+  same on the master and the delta path: `## /aw-spec-implement-backend` for the service lane,
+  `## /aw-spec-implement-frontend` for the frontend lane.
 - Constitution: the **technical** half in the service lane, the **UI** half in the frontend one.
 
 ### `build` — *compile + repair*
@@ -133,8 +132,8 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
   there is no map to read. The order is therefore inverted: the half is authored from the code,
   then the `frontend/` rule set is generated as its detail layer, then the lane's three headings
   are appended to the technical map — `## /aw-spec-ui-constitution` (what a LATER `constitution`
-  run re-ratifies from, so it behaves like the greenfield case above), `## /aw-spec-plan-ui` and
-  `## /aw-spec-implement-ui` (what the frontend lane of `plan` and `implement` load).
+  run re-ratifies from, so it behaves like the greenfield case above), `## /aw-spec-plan-frontend`
+  and `## /aw-spec-implement-frontend` (what the frontend lane of `plan` and `implement` load).
 - `onboard` **never writes** `.appweaver/stacks.json`. `lane-declare` is its sole writer and
   `select-stack` its only caller, so every lane is one a person confirmed.
 - The **document templates** it derives obey the same partition as the halves that govern them:
@@ -160,7 +159,7 @@ lane loads the technical base, the frontend lane loads the UI base. What they sh
 - Same partition, reversed: the reversed **spec** is authored with domain rules in context; the
   reversed **plan** is authored with the technical set only, so the plan stays domain-free.
 - Each lane's reversed plan is authored under its own lane's rules, as in `plan`: the backend
-  plan under `## /aw-spec-adopt`, and the frontend plan under `## /aw-spec-plan-ui`, which
+  plan under `## /aw-spec-adopt-backend`, and the frontend plan under `## /aw-spec-plan-frontend`, which
   REPLACES the backend set before that step rather than stacking on it.
 - Technical files here are **reference, not authority — the CODE wins.**
 

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

@@ -22,7 +22,7 @@ and why nothing in the format assumes there are only two lanes.
 
 **Lanes get map headings, never a `--lane` flag.** Rule maps are keyed on
 `## /aw-spec-<name>`, so a lane's rule set is reached under its own heading —
-`## /aw-spec-implement-ui` for the frontend lane of `implement`, and so on. A flag would have
+`## /aw-spec-implement-frontend` for the frontend lane of `implement`, and so on. A flag would have
 no heading to key on. Where the two lanes are folded into one command, as `plan` and
 `implement` are, the heading names the lane and the command dispatches on the declaration.
 
@@ -56,6 +56,9 @@ no heading to key on. Where the two lanes are folded into one command, as `plan`
 | `run_from` | *(optional)* **where the commands run**: `repo` (the default, and the shape of every lane written before this key existed) at the repository root, or `root` inside the lane root folder. `select-stack` decides it from where the stack's build file sits — see §3.1 |
 | `build` / `test` / `run` | project-supplied command strings the engine shells out to. These are the matched **profile's** defaults and may not fit a legacy layout — reviewing them is what `select-stack` is for. `{{root}}` in a command resolves to this lane's `root`, as seen from where the command runs (§4.2) |
 | `migrate` | *(optional)* the lane's schema-migration command, recorded only when the profile declares one. Absent, `run-migrate` falls back to `dotnet ef` and otherwise reports that nothing ran (§4.2) |
+| `contract_run` | *(optional, backend)* the command that starts the service on its own so `implement` can export its API document (§4.5). Absent, the profile's is used. `foundation` sets it from a pack's `<pack>.lane.json` |
+| `contract` | *(optional, backend)* the URL the running service serves its API document at (§4.5). Absent, the profile's is used |
+| `client` | *(optional, frontend)* the command that generates the frontend's API client from that document; `{{contract}}` in it is the document's path. No shipped profile has one: `implement` asks the developer the first time and records the answer here (§4.5) |
 
 ### Three properties matter more than the schema
 
@@ -217,6 +220,11 @@ workflow.**
   "host_patterns": [],                       // optional — where the runnable project sits, for
                                              // `{{host}}` in a command — see §4.2
   "migrate": "",                             // optional — schema migration, if the stack has one
+  "contract_run": "",                        // optional, backend — start the service to export
+                                             // its API document — see §4.5
+  "contract": "",                            // optional, backend — the URL it serves it at
+  "client": "",                              // optional, frontend — generate the API client
+                                             // from `{{contract}}` — see §4.5
   "prototype_run": "npm run dev --prefix prototype",   // frontend only — fills the prototype block
   "reserved_names": ["Event", "Request", "Response"],  // optional — names this stack's AMBIENT
                                              // scope already defines; see §4.4
@@ -434,18 +442,66 @@ A layout the table gets wrong is fixed by writing `test_root` on the lane in `st
 | `go-chi` | `backend/` | *(inside the lane root folder)* | `internal/` | — |
 | every frontend | `frontend/` | *(inside the lane root folder)* | `web/` | — |
 
+### 4.5 `contract_run`, `contract` and `client` — the API contract between the lanes
+
+The frontend lane binds to the service through the service's published API document, and
+the document that counts is the one the **built code** serves. `implement` therefore runs
+three steps between the two lanes, each of which warns rather than stops:
+
+1. **Export** (`contract-export`) — start the service with the backend lane's
+   `contract_run`, fetch its `contract` URL, write the document to
+   `<service lane root folder>/contracts/openapi.json`, and stop the service with
+   everything it started. A service already answering at the URL is used as it is, and
+   the run says it may be older than the code.
+2. **Client** (`contract-client`) — run the frontend lane's `client` command, with
+   `{{contract}}` standing for that document as seen from where the command runs.
+3. **Check** (`contract-check`) — every operation id the frontend plan cites must be an
+   `operationId` in the document.
+
+Each key is read from the lane first and from its profile second, so a lane declared
+before the keys existed still answers them. Where the values come from:
+
+| Key | Profile default | Set on the lane by |
+|---|---|---|
+| `contract_run` | `dotnet-webapi`: `dotnet run --project {{host}} -- --environment Development --urls http://localhost:5000`<br>`java-spring`: `./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8080` | `foundation`: on the pack route from the pack's `<pack>.lane.json` — the shipped .NET packs start their API project alone (the AppHost needs Docker), the Java `Hexagonal` pack its one Maven module; on the spec route from the spec's `# contract-run:` header line, or the operator's answer when it has none |
+| `contract` | `dotnet-webapi`: `http://localhost:5000/swagger/v1/swagger.json`<br>`java-spring`: `http://localhost:8080/v3/api-docs` (springdoc's default path) | `foundation`, the same way — the `# contract:` header line on the spec route |
+| `client` | none — no generator is assumed | `foundation` on the spec route, from the `# client:` header line or the operator's answer; else `implement`, which asks the first time and records the answer |
+
+On the spec route an empty answer keeps the lane's current value, so a lane nobody set
+anything on stays on the profile's default. `foundations/foundation.spec.template.txt`
+shows the three header lines; `<App>` in them is the app name given at `foundation`.
+
+`--environment Development` matters for the .NET packs: outside Development they redirect
+to HTTPS, and the export fetches over http. Their API projects also read
+`ConnectionStrings:SqliteConnection` when started without the AppHost, and the packs'
+configuration carries none, so their commands pass one. A pack's `<pack>.lane.json` sits
+beside its `.pack.txt`, names the pack's sentinel the way its files do, and is renamed with
+them:
+
+```json
+{"format": "aw-spec-pack-lane/v1",
+ "contract_run": "dotnet run --project src/AppWeaver.VerticalSlice.Service -- --environment Development --urls http://localhost:5000 --ConnectionStrings:SqliteConnection \"Data Source=App_Data/app.db\"",
+ "contract": "http://localhost:5000/swagger/v1/swagger.json"}
+```
+
 ---
 
 ## 5. Who may write this file
 
-**`lane-declare` writes it. Nothing else does, and it has exactly ONE caller** — so the
-rule is a grep, not a convention:
+**`lane-declare` writes whole lanes, and it has exactly ONE caller** — so the rule is a
+grep, not a convention:
 
 ```sh
 grep -rl "lane-declare" .appweaver/orchestrator/workflows/   # must print exactly one file
 #   aw-spec-select-stack.orch.yaml   — a person picks
 ```
 
+**`lane-set` changes three keys on a lane that is already there, and nothing else** —
+`contract_run`, `contract` and `client` (§4.5). Its callers are `foundation`, recording
+what a pack knows about starting its service, and `implement`, recording the client
+command a developer types. They cannot use `lane-declare`, which rebuilds the whole lane
+and would reset every command on it to the profile's default.
+
 `onboard` used to be a second caller. Before `select-stack` was the first command of the
 brownfield sequence a repo could reach `onboard` undeclared, so `onboard` ran its own
 detection pass, recorded what it found marked `origin: reverse-engineered`, and was gated
@@ -545,7 +601,11 @@ implementation and the twins cannot drift.
 |---|---|
 | `stack-list [--kind k] [--preselect text] [--include-none] [--suggest]` | enumerate the installed profiles; returns `select_options[]`, and `preselect` when the text names one of *this kind's* ids. `--suggest` also runs detection, so the menu **leads with** the stack this repo's files point at and `root_options[]` leads with the directory the evidence sits in |
 | `stack-detect [--kind k] [--exclude-root p]…` | match the repo's OWN files against the installed profiles — the brownfield candidate list, since an existing repo already answered the question. Writes nothing. `--exclude-root` keeps a service profile from relocating onto a subtree another lane owns |
-| `lane-declare --profile <id\|label\|none\|detected> [--kind k] [--id lane] [--source-path\|--root p] [--stack label] [--origin declared\|reverse-engineered] [--build/--test/--run/--migrate c] [--run-from repo\|root] [--no-prototype] [--require-existing-root]` | upsert a lane — **the sole writer**. `detected` declares a stack the kit ships no profile for (needs `--stack` and a lane root folder), which is how a legacy WebForms, JSP or ERB lane gets recorded at all |
+| `lane-declare --profile <id\|label\|none\|detected> [--kind k] [--id lane] [--source-path\|--root p] [--stack label] [--origin declared\|reverse-engineered] [--build/--test/--run/--migrate c] [--run-from repo\|root] [--no-prototype] [--require-existing-root]` | upsert a WHOLE lane — its one caller is `select-stack` (§5). `detected` declares a stack the kit ships no profile for (needs `--stack` and a lane root folder), which is how a legacy WebForms, JSP or ERB lane gets recorded at all |
+| `lane-set (--id lane\|--kind k) [--set KEY=VALUE]… [--unset KEY]…` | change only `contract_run`, `contract` or `client` on a lane already declared, leaving the rest of it alone. An empty VALUE changes nothing; `--unset` puts the key back on the profile's value. Called by `foundation` (a pack's lane settings) and `implement` (the client command a developer supplies) — re-declaring would reset every other command |
+| `contract-export [--timeout s]` | start the service lane with `contract_run`, fetch `contract`, save it to `<service root>/contracts/openapi.json`, stop the service and everything it started. A service already answering at the URL is used as it is, and said so (§4.5) |
+| `contract-client` | `run-phase --phase client` for the frontend lane — its `client` command, `{{contract}}` expanded |
+| `contract-check --plan p [--doc d]` | the operation ids a frontend plan cites (its §5 `Operation id` column, or a delta plan's `Contract Binding` rows) against the document's `operationId`s — by script, no model |
 | `lane-resolve [--kind k] [--id lane]` | read; exit 0 always. `exists` reports the file, `declared` reports the lanes — the shipped-but-unfilled seed is `exists:true, declared:false`. Returns the matched lane **and** both kinds flattened — `backend_source_path`, `frontend_root_exists`, `backend_build` … — so a workflow binds one variable instead of calling twice |
 | `lane-verify [--require backend\|frontend]… [--allow-missing-root] [--command phase]` | **the gate**: is the declaration usable for the phase about to run. Never writes, and **always exits 0** — the calling workflow's `verify_context` owns the stop, so the reason arrives as text |
 | `lane-probe [--kind k] [--hint text]` | read; the **file** signals for "does this lane exist" — a declared lane, and a stack named in free prose. Retained for callers that want a soft hint; the authoritative answer is the declaration, read through `lane-resolve` or `lane-verify` |
@@ -610,15 +670,20 @@ they are content the kit cannot invent:
 | `{{backend_ecosystem}}` / `{{frontend_ecosystem}}` | that lane's `ecosystem` |
 
 ```md
-## /aw-spec-plan
+## /aw-spec-plan-backend
 - guardrails/technology/{{stack}}/persistence.md
-- guardrails/technology/{{frontend_stack}}/ui-constitution.md
+
+## /aw-spec-plan-frontend
+- guardrails/technology/{{frontend_stack}}/component-architecture.md
+- guardrails/technology/{{frontend_stack}}/api-integration.{{backend_stack}}.md
 ```
 
 One map, read from a Spring repo, loads `java-spring/persistence.md`; read from a .NET repo it
-loads `dotnet-webapi/persistence.md`. A placeholder for a lane that is not declared **skips**
-that bullet — a frontend rule in a backend-only repo is not an error — and a resolved path with
-no file on disk is reported under `missing` rather than silently dropped.
+loads `dotnet-webapi/persistence.md`. Each heading holds one lane's rules, and a workflow loads
+a lane's heading only when that lane runs. A placeholder for a lane that is not declared
+**skips** that bullet — in a frontend-only repo the `api-integration.{{backend_stack}}.md`
+pairing bullet is skipped, not an error — and a resolved path with no file on disk is reported
+under `missing` rather than silently dropped.
 
 **A bullet that spells the stack out is still used**, because a shared corpus may be referenced
 on purpose. But when that directory is not one the repo declares, `resolve-tech` returns

package/assets/.appweaver/interpreter/run-skill.py

@@ -62,13 +62,18 @@ def _indent(line):
 
 
 def _strip_comment(s):
-    """Strip a trailing ' #...' comment that is outside quotes/flow."""
+    """Strip a trailing ' #...' comment that is outside quotes/flow. Inside double
+    quotes a backslash escapes the next character, so \\" does not end the string."""
     out, i, depth = [], 0, 0
     quote = None
     while i < len(s):
         c = s[i]
         if quote:
             out.append(c)
+            if quote == '"' and c == "\\" and i + 1 < len(s):
+                out.append(s[i + 1])
+                i += 2
+                continue
             if c == quote:
                 quote = None
         elif c in ("'", '"'):
@@ -93,6 +98,9 @@ def _scalar(tok):
     if tok == "" or tok == "~" or tok.lower() == "null":
         return None
     if len(tok) >= 2 and tok[0] == tok[-1] and tok[0] in "'\"":
+        if tok[0] == '"':
+            # A double-quoted value reads \" as " and \\ as \, as YAML does.
+            return re.sub(r'\\(["\\])', r"\1", tok[1:-1])
         return tok[1:-1]
     low = tok.lower()
     if low == "true":
@@ -140,7 +148,9 @@ def _parse_flow(s):
         while pos[0] < len(s):
             ch = s[pos[0]]
             if quote:
-                if ch == quote:
+                if quote == '"' and ch == "\\":
+                    pos[0] += 1  # the escaped character never closes the quote
+                elif ch == quote:
                     quote = None
             elif ch in "'\"":
                 quote = ch
@@ -328,12 +338,23 @@ def _parse_block_scalar(lines, parent_indent, folded, chomp):
         trailing += 1
 
     if folded:
-        text = ""
-        for i, ln in enumerate(block):
-            if i == 0:
-                text = ln
+        # YAML folding: one line break between two lines becomes a space, a line break
+        # followed by k empty lines becomes k newlines, and the break before or after a
+        # more-indented line is kept as it is.
+        parts, prev, empties = [], None, 0
+        for ln in block:
+            if ln == "":
+                empties += 1
+                continue
+            if prev is None:
+                parts.append("\n" * empties)
+            elif prev[:1] not in " \t" and ln[:1] not in " \t":
+                parts.append("\n" * empties if empties else " ")
             else:
-                text += ("\n" if (block[i - 1] == "" or ln == "") else " ") + ln
+                parts.append("\n" * (empties + 1))
+            parts.append(ln)
+            prev, empties = ln, 0
+        text = "".join(parts)
     else:
         text = "\n".join(block)
 

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

@@ -130,6 +130,9 @@ workflow:
                                              # the context's CANONICAL model — the aggregate root,
                                              # its entities and its invariants live here, not in the
                                              # spec and not in this plan.
+      - { path: .appweaver/memory/constitution.technical.md, optional: true }
+                                             # the lane's ratified technology base, the same one
+                                             # the master plan is authored under — no domain.
       - { path: "{{cr_dir}}/delta-slice-analyze-report.md", optional: true }
                                              # WHAT THE LAST GATE FOUND, when this change
                                              # has already been through analyze-slice-delta.
@@ -191,7 +194,9 @@ workflow:
         lane" with every addition or change to this feature's published surface, as field
         shapes. That table is the only part of this document the frontend delta plan may
         bind against; a contract the UI needs and this document never states becomes a
-        client-side workaround. "None" when the surface is unchanged.
+        client-side workaround. "None" when the surface is unchanged. Each row carries the
+        endpoint's operation id: a changed endpoint keeps the one the master plan gives
+        it, and a new endpoint gets one unique across the service.
       - Stay technology-agnostic (no code) and keep the master's form: behaviour as
         signatures + pre/post/invariant/raises, contracts as field shapes.
       - TWO CASES — decide from the delta-spec in context:
@@ -208,11 +213,12 @@ workflow:
 
   # ══════════ THE LANE SWAP — the frontend's rules replace the backend's ═══════
   # The delta twin of the swap `plan` performs before its own master frontend sections.
-  # Sticky standards only accumulate, and the caller loaded BOTH lanes' rule sets before
-  # including this module, so without this the service delta plan is authored with the UI
-  # rules in its envelope and the experience delta plan with the service rules. `replace`
-  # resets to the workflow's declared seed and loads `## /aw-spec-plan-ui`, so the backend
-  # delta above kept the service set and everything below this line is the frontend's.
+  # The caller loads only the service lane's rules (`## /aw-spec-plan-backend`, when that
+  # lane is declared) before including this module, and sticky standards only accumulate,
+  # so without this the experience delta plan would be authored with the service rules in
+  # its envelope. `replace` resets to the workflow's declared seed and loads
+  # `## /aw-spec-plan-frontend`, so the backend delta above is authored under the service
+  # set and everything below this line under the frontend's.
   #
   # Conditioned on the same flag as the lane it precedes: a change with no frontend half
   # authors nothing here and must not have its envelope swapped out from under the
@@ -221,7 +227,7 @@ workflow:
     condition: "{{fe_existing}} == true"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
-    with: { command: aw-spec-plan-ui, replace: "true" }
+    with: { command: aw-spec-plan-frontend, replace: "true" }
 
   # ═════════════════════ FRONTEND LANE — the experience delta plan ═════════════
   - id: ctx_frontend_delta
@@ -292,6 +298,10 @@ workflow:
         and introduce no server-side behaviour or persistence assumption. What the
         experience needs and the surface does not offer goes under "Contract deltas
         needed", raised back to the service lane — never worked around in the client.
+      - A BINDING ROW'S ELEMENT LEADS WITH ITS OPERATION ID — `OperationId` · `VERB
+        /route` — copied exactly from the service delta's table or, for an endpoint the
+        change does not touch, the master backend plan. Implement looks the endpoint up by
+        it in the service's exported API document.
       - UX- IS THIS DOCUMENT'S TO REALISE. The service plan excludes the spec's Experience
         Standards by contract, so a UX- item in the delta-spec that reaches neither plan
         is a dropped requirement.

package/assets/.appweaver/orchestrator/modules/domain-select.orch.yaml

@@ -62,7 +62,7 @@ workflow:
     require_value: dg_gate
     equals: "continue"
     on_mismatch: stop
-    on_mismatch_message: "Exited — run /appweaver select-domain, or set \"domain\" in .appweaver/domain.json to a folder under guardrails/ that holds domain-rule-bindings.md (project-specific by default), then re-run."
+    on_mismatch_message: "Exited — run /appweaver select-domain, or set 'domain' in .appweaver/domain.json to a folder under guardrails/ that holds domain-rule-bindings.md (project-specific by default), then re-run."
 
   # 3. Selection box — only when a rule map with candidates exists.
   - id: select_mode

package/assets/.appweaver/orchestrator/modules/foundation-pack.orch.yaml

@@ -6,6 +6,9 @@
 # collisions, unpack into the lane root folder exactly as packed with the sentinel renamed,
 # optionally add the reference sample on top, and check that no sentinel is left behind.
 #
+# Its LANE SETTINGS (<pack name>.lane.json beside the pack), when it has any, are recorded
+# on the lane once it is unpacked.
+#
 # Every file in a pack lands as packed, replacing a file already there — except the ones
 # its RULE FILE (<pack name>.rules.json beside the pack) says to merge. The model is used
 # ONLY for those merges: an `agent_author` (read-only generation, the ENGINE writes the
@@ -63,6 +66,13 @@ workflow:
       fp_clean: ""
       fp_residue: ""
       fp_residue_note: "not checked"
+      fp_lane_found: "false"
+      fp_lane_file: ""
+      fp_lane_contract_run: ""
+      fp_lane_contract: ""
+      fp_lane_client: ""
+      fp_lane_recorded: ""
+      fp_lane_note: ""
 
   # 1. Locate the bundle + its unpacker and read the (bounded) pack header: the sentinel,
   #    the file count, and whether a Reference pack ships beside it.
@@ -187,6 +197,39 @@ workflow:
     message_var: fl_status
     on_false_message: "NOT scaffolded — the {{fl_name}} unpacker failed and wrote {{fp_written}} file(s). Its output ends: {{fp_unpack_out}}"
 
+  # 5b. The pack's LANE SETTINGS (<pack name>.lane.json beside it): what only the pack
+  #     knows about the project it scaffolds — chiefly how its service is started on its
+  #     own so implement can export the API document. Recorded on the lane with lane-set;
+  #     a key the file leaves empty is not touched, and a pack with no such file leaves
+  #     the lane on its stack profile's values.
+  - id: fp_lane_settings
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: foundation-pack-lane
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}"]
+    outputs:
+      - { name: fp_lane_found,        from: "$.found" }
+      - { name: fp_lane_file,         from: "$.file" }
+      - { name: fp_lane_contract_run, from: "$.contract_run" }
+      - { name: fp_lane_contract,     from: "$.contract" }
+      - { name: fp_lane_client,       from: "$.client" }
+
+  - id: fp_lane_record
+    action: execute_script
+    condition: "{{fp_lane_found}} == true"
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-set
+    args: ["--id", "{{fl_lane_id}}", "--set", "contract_run={{fp_lane_contract_run}}", "--set", "contract={{fp_lane_contract}}", "--set", "client={{fp_lane_client}}"]
+    outputs:
+      - { name: fp_lane_recorded, from: "$.ok" }
+
+  - id: fp_lane_noted
+    action: set
+    condition: "{{fp_lane_recorded}} == true"
+    vars: { fp_lane_note: "; the pack's API-export settings ({{fp_lane_file}}) recorded on the {{fl_lane_id}} lane" }
+
   # 6. The merges the rule file asks for: the file that was there (put aside) and the
   #    pack's version (now on disk) become one, as the rule's instruction says.
   - id: fp_merge
@@ -346,4 +389,4 @@ workflow:
     action: set
     vars:
       fl_files: "{{fp_written}}"
-      fl_status: "scaffolded from the {{fl_name}} pack — {{fp_written}} file(s) into {{fl_source_path}}{{fp_tests_note}}{{fp_rules_note}}{{fp_ref_note}}; {{fp_residue_note}}"
+      fl_status: "scaffolded from the {{fl_name}} pack — {{fp_written}} file(s) into {{fl_source_path}}{{fp_tests_note}}{{fp_rules_note}}{{fp_ref_note}}{{fp_lane_note}}; {{fp_residue_note}}"

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

@@ -22,7 +22,8 @@
 #           gates on), and its own build command can be run on it.
 #
 # The spec actually used is copied to .appweaver/foundation/<lane>.spec.md — the record of
-# what the project was built from.
+# what the project was built from. The API-contract settings its header gives — or the
+# operator types when it gives none — are recorded on the lane once the project is built.
 #
 # Every refusal RETURNS rather than stops, with the reason in fl_status, so the run
 # carries on with the next lane.
@@ -68,6 +69,30 @@ workflow:
       fs_build_ack: ""
       fs_build_ok: ""
       fs_build_note: "build not run — /appweaver build compiles it and repairs compile errors"
+      fs_hdr_contract_run: ""
+      fs_hdr_contract: ""
+      fs_hdr_client: ""
+      fs_settings_text: "none"
+      fs_placeholder: ""
+      fs_is_backend: "false"
+      fs_is_frontend: "false"
+      fs_need_run: "false"
+      fs_need_url: "false"
+      fs_need_client: "false"
+      fs_ans_contract_run: ""
+      fs_ans_contract: ""
+      fs_ans_client: ""
+      fs_set_run: ""
+      fs_set_url: ""
+      fs_set_client: ""
+      fs_cur_contract_run: ""
+      fs_cur_contract: ""
+      fs_cur_client: ""
+      fs_cur_run_shown: "none — the export is skipped until one is set"
+      fs_cur_url_shown: "none — the export is skipped until one is set"
+      fs_cur_client_shown: "none — implement asks for one before it generates the frontend"
+      fs_lane_written: ""
+      fs_lane_note: ""
 
   # 1. A lane that already had files reaches this module only when the operator agreed, in
   #    foundation-lane, to overwrite them. The agent is told so, with what that means for
@@ -120,26 +145,36 @@ workflow:
     condition: "{{fl_route}} == spec"
     script: { ref: actions }
     subcommand: foundation-spec-capture
-    args: ["--lane", "{{fl_lane_id}}", "--kind", "{{fl_kind}}", "--file", "{{fl_spec_file}}"]
+    args: ["--lane", "{{fl_lane_id}}", "--kind", "{{fl_kind}}", "--file", "{{fl_spec_file}}", "--app", "{{app}}"]
     outputs:
       - { name: fs_ok,        from: "$.ok" }
       - { name: fs_spec_path, from: "$.spec_path" }
       - { name: fs_source,    from: "$.source" }
       - { name: fs_title,     from: "$.title" }
       - { name: fs_reason,    from: "$.reason" }
+      - { name: fs_hdr_contract_run, from: "$.contract_run" }
+      - { name: fs_hdr_contract,     from: "$.contract" }
+      - { name: fs_hdr_client,       from: "$.client" }
+      - { name: fs_settings_text,    from: "$.settings_text" }
+      - { name: fs_placeholder,      from: "$.placeholder" }
 
   - id: fs_capture_manual
     action: execute_script
     condition: "{{fl_route}} == manual"
     script: { ref: actions }
     subcommand: foundation-spec-capture
-    args: ["--lane", "{{fl_lane_id}}", "--kind", "{{fl_kind}}", "--input", "{{fs_spec_input}}"]
+    args: ["--lane", "{{fl_lane_id}}", "--kind", "{{fl_kind}}", "--input", "{{fs_spec_input}}", "--app", "{{app}}"]
     outputs:
       - { name: fs_ok,        from: "$.ok" }
       - { name: fs_spec_path, from: "$.spec_path" }
       - { name: fs_source,    from: "$.source" }
       - { name: fs_title,     from: "$.title" }
       - { name: fs_reason,    from: "$.reason" }
+      - { name: fs_hdr_contract_run, from: "$.contract_run" }
+      - { name: fs_hdr_contract,     from: "$.contract" }
+      - { name: fs_hdr_client,       from: "$.client" }
+      - { name: fs_settings_text,    from: "$.settings_text" }
+      - { name: fs_placeholder,      from: "$.placeholder" }
 
   - id: fs_capture_gate
     action: verify_context
@@ -165,7 +200,7 @@ workflow:
   - id: fs_rules_why_project
     action: set
     condition: "{{tech_domain}} == "
-    vars: { fs_rules_why: "no project is named in .appweaver/domain.json — run /appweaver select-domain, or set \"domain\" to a folder under guardrails/ (project-specific by default)" }
+    vars: { fs_rules_why: "no project is named in .appweaver/domain.json — run /appweaver select-domain, or set 'domain' to a folder under guardrails/ (project-specific by default)" }
 
   - id: fs_rules_why_heading
     action: set
@@ -278,6 +313,19 @@ workflow:
           /appweaver implement from the plans, so add none the spec does not ask for.
         - The project must build with `{{fl_build}}` run in {{fl_workdir}}. Restore or
           install what that needs; run the build once if you can and fix what it reports.
+        - THE API CONTRACT SETTINGS the spec's header gives: {{fs_settings_text}}. They are
+          recorded on the lane, and /appweaver implement uses them before it generates the
+          frontend, so the project you build has to honour them exactly:
+            · a START COMMAND (backend) — the API starts with exactly that command, run in
+              {{fl_workdir}}, ON ITS OWN: no orchestration host, and nothing it needs that
+              is not on this machine. Name the project so the path the command names exists.
+            · a DOCUMENT URL (backend) — the running API serves its OpenAPI document at
+              exactly that URL, over http, on the port it names.
+            · a CLIENT COMMAND (frontend) — that command can run in {{fl_workdir}}: install
+              its tool as a development dependency. Do not run it; the service's document
+              does not exist yet.
+          A backend built without them still serves an OpenAPI document; say at what URL,
+          and how the API starts on its own, in your summary.
         - Do not commit, push, or change git configuration.
 
       List every file you created or changed in `files` (paths relative to the repository
@@ -373,9 +421,128 @@ workflow:
     condition: "{{fs_build_ok}} == false"
     vars: { fs_build_note: "build FAILED — run /appweaver build, which repairs compile errors: {{fs_build_tail}}" }
 
+  # 8. THE API CONTRACT SETTINGS — what implement uses between the lanes to export the
+  #    service's OpenAPI document and generate the frontend's client from it
+  #    (STACK-PROFILES.md §4.5). A backend lane needs its start command and document URL,
+  #    a frontend lane its client command. Each comes from the spec's header
+  #    (`# contract-run:`, `# contract:`, `# client:`, read at capture); one the header
+  #    does not give is asked for, and an empty answer keeps the lane's current value —
+  #    the stack profile's, unless something set it already. What there is, is recorded
+  #    on the lane with lane-set, as the pack route records a pack's .lane.json.
+  - id: fs_kind_backend
+    action: set
+    condition: "{{fl_kind}} == backend"
+    vars: { fs_is_backend: "true" }
+  - id: fs_kind_frontend
+    action: set
+    condition: "{{fl_kind}} == frontend"
+    vars: { fs_is_frontend: "true" }
+  - id: fs_need_run_arm
+    action: set
+    condition: "{{fs_hdr_contract_run}} == "
+    vars: { fs_need_run: "{{fs_is_backend}}" }
+  - id: fs_need_url_arm
+    action: set
+    condition: "{{fs_hdr_contract}} == "
+    vars: { fs_need_url: "{{fs_is_backend}}" }
+  - id: fs_need_client_arm
+    action: set
+    condition: "{{fs_hdr_client}} == "
+    vars: { fs_need_client: "{{fs_is_frontend}}" }
+
+  # The lane's current values, shown as what an empty answer keeps.
+  - id: fs_current
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-resolve
+    args: ["--id", "{{fl_lane_id}}"]
+    outputs:
+      - { name: fs_cur_contract_run, from: "$.backend_contract_run" }
+      - { name: fs_cur_contract,     from: "$.backend_contract" }
+      - { name: fs_cur_client,       from: "$.frontend_client" }
+  - id: fs_cur_run_known
+    action: set
+    condition: "{{fs_cur_contract_run}} != "
+    vars: { fs_cur_run_shown: "{{fs_cur_contract_run}}" }
+  - id: fs_cur_url_known
+    action: set
+    condition: "{{fs_cur_contract}} != "
+    vars: { fs_cur_url_shown: "{{fs_cur_contract}}" }
+  - id: fs_cur_client_known
+    action: set
+    condition: "{{fs_cur_client}} != "
+    vars: { fs_cur_client_shown: "{{fs_cur_client}}" }
+
+  - id: fs_ask_contract_run
+    action: ask
+    condition: "{{fs_need_run}} == true"
+    prompt: |
+      How does the API in lane `{{fl_lane_id}}` start ON ITS OWN? /appweaver implement starts
+      it with this command to fetch its OpenAPI document before it generates the frontend.
+      The spec's header gives no `# contract-run:`.
+      Type the command — it runs in {{fl_workdir}} — with no orchestration host and nothing
+      the API cannot reach on this machine.
+      Leave it empty to keep the current one: {{fs_cur_run_shown}}
+    answer_var: fs_ans_contract_run
+  - id: fs_ask_contract
+    action: ask
+    condition: "{{fs_need_url}} == true"
+    prompt: |
+      At what URL does that running API serve its OpenAPI document? The spec's header gives
+      no `# contract:`.
+      Leave it empty to keep the current one: {{fs_cur_url_shown}}
+    answer_var: fs_ans_contract
+  - id: fs_ask_client
+    action: ask
+    condition: "{{fs_need_client}} == true"
+    prompt: |
+      Which command generates this frontend's API client from the service's OpenAPI
+      document? The spec's header gives no `# client:`.
+      It runs in {{fl_workdir}}, and {{fs_placeholder}} in it stands for the document's path —
+      for example: npx openapi-typescript {{fs_placeholder}} -o lib/api/schema.d.ts
+      Leave it empty to keep the current one: {{fs_cur_client_shown}}
+    answer_var: fs_ans_client
+
+  # What to record: the header's value for this lane's kind, or the answer where it gave
+  # none. An empty value is left out by lane-set, so the lane keeps what it has.
+  - id: fs_set_backend
+    action: set
+    condition: "{{fs_is_backend}} == true"
+    vars: { fs_set_run: "{{fs_hdr_contract_run}}", fs_set_url: "{{fs_hdr_contract}}" }
+  - id: fs_set_run_answer
+    action: set
+    condition: "{{fs_need_run}} == true"
+    vars: { fs_set_run: "{{fs_ans_contract_run}}" }
+  - id: fs_set_url_answer
+    action: set
+    condition: "{{fs_need_url}} == true"
+    vars: { fs_set_url: "{{fs_ans_contract}}" }
+  - id: fs_set_frontend
+    action: set
+    condition: "{{fs_is_frontend}} == true"
+    vars: { fs_set_client: "{{fs_hdr_client}}" }
+  - id: fs_set_client_answer
+    action: set
+    condition: "{{fs_need_client}} == true"
+    vars: { fs_set_client: "{{fs_ans_client}}" }
+
+  - id: fs_lane_record
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: lane-set
+    args: ["--id", "{{fl_lane_id}}", "--set", "contract_run={{fs_set_run}}", "--set", "contract={{fs_set_url}}", "--set", "client={{fs_set_client}}"]
+    outputs:
+      - { name: fs_lane_written, from: "$.written" }
+  - id: fs_lane_noted
+    action: set
+    condition: "{{fs_lane_written}} == true"
+    vars: { fs_lane_note: "; API-contract settings recorded on the {{fl_lane_id}} lane" }
+
   - id: fs_done
     action: set
     vars:
       fl_spec_path: "{{fs_spec_path}}"
       fl_files: "{{fs_files}}"
-      fl_status: "built from the spec in {{fs_spec_path}} (from {{fs_source}}) into {{fl_source_path}} — {{fs_summary}}; {{fs_build_note}}"
+      fl_status: "built from the spec in {{fs_spec_path}} (from {{fs_source}}) into {{fl_source_path}} — {{fs_summary}}; {{fs_build_note}}{{fs_lane_note}}"