aw-spec-cli 0.1.27 → 0.1.29

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

@@ -316,5 +316,5 @@ outputs:
   api_detected: "{{api_detected}}"
   ui_detected: "{{ui_detected}}"
   prototype: "{{prototype}}"
-  note: "Lanes persisted to .appweaver/stacks.json. Each lane carries a STACK and a LANE ROOT FOLDER, and both are load-bearing. The LANE ROOT FOLDER is ownership: implement's service lane writes its code only under the service lane's and its frontend lane only under the UI lane's, build/test/run act on it, and onboard reverse-engineers out of it. Each lane also owns a TEST PATH, taken from its stack profile — tests/ beside a .NET src/, the lane root folder itself for a stack that keeps its tests inside — and implement writes the lane's tests there. Overlapping paths of either kind are refused here rather than discovered later as two generators writing one file. The build/test/run commands are project-supplied strings the engine shells out to, which is how it stays stdlib-only and stack-ignorant. api_detected / ui_detected report what this repo's own files pointed at, whether or not it was chosen, as "<stack> at <path>" — or "nothing detected" on a greenfield repo with nothing to detect. A lane root folder that does not exist yet is NORMAL here and reported rather than refused: greenfield declares src/ before implement creates it. The on-disk check runs in the phases that read the subtree — implement, build, run and onboard all call lane-verify and STOP with the fix named. Declining a lane with (none) is a real declaration and removes any lane of that kind a previous run left behind; it is also what stops that lane's constitution half and rule files being authored. `prototype` is not a lane — it has a root and a run command so an operator can open it, and nothing else. Re-run this workflow any time to re-stack a lane, move a lane root folder, or drop a lane with (none); it is the only workflow that may write this file."
+  note: "Lanes persisted to .appweaver/stacks.json. Each lane carries a STACK and a LANE ROOT FOLDER, and both are load-bearing. The LANE ROOT FOLDER is ownership: implement's service lane writes its code only under the service lane's and its frontend lane only under the UI lane's, build/test/run act on it, and onboard reverse-engineers out of it. Each lane also owns a TEST PATH, taken from its stack profile — tests/ beside a .NET src/, the lane root folder itself for a stack that keeps its tests inside — and implement writes the lane's tests there. Overlapping paths of either kind are refused here rather than discovered later as two generators writing one file. The build/test/run commands are project-supplied strings the engine shells out to, which is how it stays stdlib-only and stack-ignorant. api_detected / ui_detected report what this repo's own files pointed at, whether or not it was chosen, as '<stack> at <path>' — or 'nothing detected' on a greenfield repo with nothing to detect. A lane root folder that does not exist yet is NORMAL here and reported rather than refused: greenfield declares src/ before implement creates it. The on-disk check runs in the phases that read the subtree — implement, build, run and onboard all call lane-verify and STOP with the fix named. Declining a lane with (none) is a real declaration and removes any lane of that kind a previous run left behind; it is also what stops that lane's constitution half and rule files being authored. `prototype` is not a lane — it has a root and a run command so an operator can open it, and nothing else. Re-run this workflow any time to re-stack a lane, move a lane root folder, or drop a lane with (none); it is the only workflow that may write this file."
   next: "GREENFIELD: /appweaver foundation → constitution → specify. The project rules live in guardrails/project-specific/, which .appweaver/domain.json names by default — fill in its rule files and its two maps; /appweaver select-domain switches to another project folder under guardrails/ when you keep more than one. On a project with no specs yet, constitution creates the default bounded context MainContext and its feature CoreFeature and makes both active; to use your own names, run /appweaver select-bounded-context <Name> and then /appweaver select-feature <Name> before specify. Once any bounded context exists, select-feature refuses to run until one is selected. foundation scaffolds every lane declared here in one run, backend then frontend — from a verified pack, from a spec the agent builds the project from, or skipped for a lane whose code already exists — and a spec build follows the technical rules the active project maps under `## /aw-spec-foundation-backend` and `## /aw-spec-foundation-frontend`. BROWNFIELD: /appweaver inventory — it scans the lane root folders declared here and proposes the bounded contexts and features as specs/proposed-inventory.md; edit that map, run /appweaver inventory apply, then /appweaver onboard <Context> once per bounded context, which reverse-engineers the governance out of the same lane root folders and activates it: onboard creates guardrails/brf-<domain>/ from the code and names it in .appweaver/domain.json. Run this workflow FIRST in either sequence: foundation scaffolds into the lane root folders declared here, constitution reads the declaration to decide which halves to author, and inventory and onboard read it to decide what to scan."

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

@@ -643,7 +643,7 @@ workflow:
         action: verify_context
         require_true: nn_compliant
         on_false: stop
-        on_false_message: "The answer to \"{{c.question}}\" departs from NON-NEGOTIABLE principle {{nn_principle}}: {{nn_why}}. That principle is ratified in .appweaver/memory/ and this answer has no approver — it was settled in this run, not by a domain owner, and the constitution's Governance section holds that a deviation with no named approver is a defect rather than a decision. Re-run specify and answer in a way the principle allows; if the project genuinely intends to depart from it, amend the constitution through its own amendment process FIRST (which names the approver the departure needs) and re-run. Nothing was written to {{quality_target}} for this clarification."
+        on_false_message: "The answer to '{{c.question}}' departs from NON-NEGOTIABLE principle {{nn_principle}}: {{nn_why}}. That principle is ratified in .appweaver/memory/ and this answer has no approver — it was settled in this run, not by a domain owner, and the constitution's Governance section holds that a deviation with no named approver is a defect rather than a decision. Re-run specify and answer in a way the principle allows; if the project genuinely intends to depart from it, amend the constitution through its own amendment process FIRST (which names the approver the departure needs) and re-run. Nothing was written to {{quality_target}} for this clarification."
 
       - id: resolve_clar
         action: agent_author

package/assets/.appweaver/scripts/bash/aw-spec-actions.sh

@@ -47,6 +47,12 @@
 #                     Always exits 0 — the workflow's verify_context owns the stop)
 #   lane-probe       [--kind <k>] [--hint <text>]  -> {declared, declared_profile, hint_profile, hint_terms[], signals[], any, evidence}
 #                    (the FILE signals for "does this lane exist"; resolve-tech carries the rule signal)
+#   lane-set         (--id <lane>|--kind <k>) [--set KEY=VALUE]… [--unset KEY]…  -> {ok, lane_id, set, removed, written}
+#                    (KEY: contract_run, contract, client; an empty VALUE changes nothing)
+#   contract-export  [--timeout <s>]               -> {ok, ran, cmd, url, doc, doc_exists, operations, unnamed, already_running, reason, log_tail}
+#                    (start the service lane with contract_run, save the document at contract, stop it)
+#   contract-client                                -> run-phase result for the frontend lane's `client` command
+#   contract-check   --plan <p> [--doc <d>]        -> {ok, cited, ids[], missing[], uncited, doc_exists, reason}
 #   list-features    [--preselect <name>] [--bundle <dir>]  -> {features[], names[], count, select_options[], sentinel}   (specs/ ∪ features the OKF concepts serve)
 #   set-feature      --feature <name>              -> {feature, feature_dir, spec_file, existed, created, spec_exists}
 #   default-scope    --context <name> --feature <name>  -> {created, skipped_reason, context_dir, feature_dir}
@@ -70,8 +76,8 @@
 #                    (one lane's pick list: its packs + specs, then [manual spec] and [skip])
 #   foundation-choice --selection <option> [same filters as foundation-list]
 #                                                  -> {ok, route (pack|spec|manual|skip), name, file, reason}
-#   foundation-spec-capture --lane <id> [--kind <k>] (--file <path> | --input <path|text>)
-#                                                  -> {ok, spec_path, source, chars, title, reason}
+#   foundation-spec-capture --lane <id> [--kind <k>] (--file <path> | --input <path|text>) [--app <A>]
+#                                                  -> {ok, spec_path, source, chars, title, reason, contract_run, contract, client, settings_text}
 #   foundation-lane-files --source <p> [--test <p>] [--workdir <p>] [--profile <id>]
 #                                                  -> {has_files, count, sample[], generated[], root_files[], folders[], workdir, summary}
 #   foundation-snapshot --out <repo-relative file>  -> {ok, snapshot, entries}
@@ -85,6 +91,8 @@
 #                                                  -> {ok, reason, rules_file, rules, merges[], merge_count, stale[], note}
 #                    (what the pack's <pack name>.rules.json asks of this unpack; puts the files to merge aside)
 #   foundation-rules-done [--state <folder>]       -> {ok, removed}
+#   foundation-pack-lane --name <F> --app <A>      -> {found, file, contract_run, contract, client, reason}
+#                    (the lane settings in the pack's <pack name>.lane.json, sentinel renamed)
 #   foundation-verify --out <d> --sentinel <s>     -> {clean, residue[]}
 #   list-components                                -> {components[]}  (foundations/dotnet/components/* with integration.md)
 #   find-host-project                              -> {found, program_cs, project_dir, csproj}
@@ -717,9 +725,10 @@ cmd_set_domain() {
 # The lane model. All four delegate to the shared python core so the bash and
 # powershell twins cannot drift: the JSON contract has one implementation.
 #
-# lane-declare is the SOLE WRITER of .appweaver/stacks.json and has exactly one
-# caller (aw-spec-select-stack). lane-resolve can never write — which is why
-# these are two subcommands rather than one with a mode flag.
+# lane-declare writes WHOLE lanes into .appweaver/stacks.json and has exactly one caller
+# (aw-spec-select-stack); lane-set changes only the API-contract keys on a lane already
+# there (foundation and implement call it). lane-resolve can never write — which is why
+# these are separate subcommands rather than one with a mode flag.
 _aw_stack_py() {
     local repo_root; repo_root=$(get_repo_root)
     local core="$SCRIPT_DIR/../python/aw-stack.py"
@@ -833,6 +842,60 @@ cmd_lane_resolve() {
     _aw_stack_py resolve "${fwd[@]}"
 }
 
+# Change the API-contract keys (contract_run, contract, client) on a lane already
+# declared, leaving the rest of it alone. `--set KEY=` with an empty value changes
+# nothing; `--unset KEY` removes one. Callers: foundation (a pack's lane settings) and
+# implement (the client command a developer supplies).
+cmd_lane_set() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --id|--kind|--set|--unset) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "lane-set (--id <lane>|--kind backend|frontend) [--set KEY=VALUE]… [--unset KEY]…  (KEY: contract_run, contract, client)"; return 0 ;;
+            *) echo "lane-set: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py set "${fwd[@]}"
+}
+
+# ─────────────── contract-export / contract-client / contract-check ───────────────
+# The API contract between the lanes: export the service lane's API document from the
+# running service, generate the frontend lane's client from it, and check the operation
+# ids a frontend plan cites against it. All three delegate to aw-stack.py.
+cmd_contract_export() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --timeout) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "contract-export [--timeout <seconds>]  -> {ok, ran, cmd, url, doc, doc_exists, operations, unnamed, already_running, reason, log_tail}"; return 0 ;;
+            *) echo "contract-export: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-export "${fwd[@]}"
+}
+
+cmd_contract_client() {
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --help|-h) echo "contract-client  -> run-phase --phase client for the frontend lane"; return 0 ;;
+            *) echo "contract-client: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py run-phase --phase client --kind frontend
+}
+
+cmd_contract_check() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --plan|--doc) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "contract-check --plan <frontend plan> [--doc <api document>]  -> {ok, cited, ids, missing, uncited, doc_exists, reason}"; return 0 ;;
+            *) echo "contract-check: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-check "${fwd[@]}"
+}
+
 # The gate: is the declaration USABLE for the phase about to run. --require names a
 # lane kind the phase cannot run without and is repeatable; every DECLARED lane is
 # checked for a sound lane root folder whether or not it was required, because a stack
@@ -2131,12 +2194,14 @@ cmd_foundation_choice() {
 # Copy the spec a lane is about to be built from to .appweaver/foundation/<lane>.spec.md
 # — from a bundle's *.spec.txt (--file), or from what the operator gave (--input: a path
 # when it names a file, the spec text otherwise). Always exits 0; `ok` carries the verdict.
+# Also returns the lane settings the spec's header gives (contract_run, contract, client),
+# with `<App>` replaced by --app.
 cmd_foundation_spec_capture() {
     local -a fwd=()
     while [ $# -gt 0 ]; do
         case "$1" in
-            --lane|--kind|--file|--input) fwd+=("$1" "$2"); shift 2 ;;
-            --help|-h) echo "foundation-spec-capture --lane <id> [--kind <k>] (--file <path> | --input <path|text>)  -> {ok, spec_path, source, chars, title, reason}"; return 0 ;;
+            --lane|--kind|--file|--input|--app) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "foundation-spec-capture --lane <id> [--kind <k>] (--file <path> | --input <path|text>) [--app <App>]  -> {ok, spec_path, source, chars, title, reason, contract_run, contract, client, settings_text}"; return 0 ;;
             *) echo "foundation-spec-capture: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -2367,6 +2432,20 @@ cmd_foundation_rules_done() {
     _aw_foundation_py rules-done "${fwd[@]}"
 }
 
+# A pack's lane settings (<pack name>.lane.json beside it), sentinel renamed — what
+# foundation records on the lane with lane-set once the pack is unpacked.
+cmd_foundation_pack_lane() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --name|--app) fwd+=("$1" "$2"); shift 2 ;;
+            --help|-h) echo "foundation-pack-lane --name <F> --app <A>  -> {found, file, contract_run, contract, client, reason}"; return 0 ;;
+            *) echo "foundation-pack-lane: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_foundation_py pack-lane "${fwd[@]}"
+}
+
 # ─────────────────────────── foundation-verify ─────────────────────────────
 # Scan the output tree for leftover sentinel tokens (should be none).
 cmd_foundation_verify() {
@@ -5200,6 +5279,10 @@ case "$sub" in
     lane-resolve)     cmd_lane_resolve "$@" ;;
     lane-verify)      cmd_lane_verify "$@" ;;
     lane-probe)       cmd_lane_probe "$@" ;;
+    lane-set)         cmd_lane_set "$@" ;;
+    contract-export)  cmd_contract_export "$@" ;;
+    contract-client)  cmd_contract_client "$@" ;;
+    contract-check)   cmd_contract_check "$@" ;;
     list-contexts)    cmd_list_contexts "$@" ;;
     set-context)      cmd_set_context "$@" ;;
     list-features)    cmd_list_features "$@" ;;
@@ -5255,6 +5338,7 @@ case "$sub" in
     foundation-verify) cmd_foundation_verify "$@" ;;
     foundation-rules) cmd_foundation_rules "$@" ;;
     foundation-rules-done) cmd_foundation_rules_done "$@" ;;
+    foundation-pack-lane) cmd_foundation_pack_lane "$@" ;;
     list-components)  cmd_list_components "$@" ;;
     component-catalog) cmd_component_catalog "$@" ;;
     component-verify) cmd_component_verify "$@" ;;

package/assets/.appweaver/scripts/powershell/aw-spec-actions.ps1

@@ -563,12 +563,11 @@ function Invoke-SetDomain {
 # SAME python core, so the JSON contract has one implementation and the pair cannot
 # drift.
 #
-# lane-declare is the SOLE WRITER of .appweaver/stacks.json, with two callers:
-# aw-spec-select-stack, where a person picks, and aw-spec-onboard, which declares
-# what it reverse-engineered (those lanes carry origin: reverse-engineered, and
-# onboard never overwrites a lane that is already declared). stack-detect proposes
-# candidates and writes nothing. lane-resolve can never write — which is why these
-# are separate subcommands rather than one with a mode flag.
+# lane-declare writes WHOLE lanes into .appweaver/stacks.json and has exactly one caller:
+# aw-spec-select-stack, where a person picks. lane-set changes only the API-contract keys
+# on a lane already there (foundation and implement call it).
+# stack-detect proposes candidates and writes nothing. lane-resolve can never write —
+# which is why these are separate subcommands rather than one with a mode flag.
 function Invoke-AwStackCore {
     param([string]$Op, [string[]]$Rest)
     $py = Get-Py
@@ -641,6 +640,52 @@ function Invoke-LaneResolve {
     Invoke-AwStackCore -Op 'resolve' -Rest $fwd
 }
 
+# Change the API-contract keys (contract_run, contract, client) on a lane already
+# declared. Twin of bash cmd_lane_set.
+function Invoke-LaneSet {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--id','--kind','--set','--unset' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            default { Write-Error "lane-set: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'set' -Rest $fwd
+}
+
+# ─────────────── contract-export / contract-client / contract-check ───────────────
+# Twins of the bash cmd_contract_export / cmd_contract_client / cmd_contract_check.
+function Invoke-ContractExport {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--timeout' { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            default { Write-Error "contract-export: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'contract-export' -Rest $fwd
+}
+
+function Invoke-ContractClient {
+    param([string[]]$Rest)
+    if ($Rest.Count -gt 0) { Write-Error "contract-client: unknown arg '$($Rest[0])'"; exit 1 }
+    Invoke-AwStackCore -Op 'run-phase' -Rest @('--phase', 'client', '--kind', 'frontend')
+}
+
+function Invoke-ContractCheck {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--plan','--doc' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            default { Write-Error "contract-check: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'contract-check' -Rest $fwd
+}
+
 # The gate: is the declaration USABLE for the phase about to run. Twin of bash
 # cmd_lane_verify. --require names a lane kind the phase cannot run without;
 # --allow-missing-root is the greenfield state, where a lane root folder is declared
@@ -1639,7 +1684,7 @@ function Invoke-FoundationSpecCapture {
     $fwd = @()
     for ($i = 0; $i -lt $Rest.Count; $i++) {
         switch ($Rest[$i]) {
-            { $_ -in '--lane','--kind','--file','--input' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            { $_ -in '--lane','--kind','--file','--input','--app' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
             default { Write-Error "foundation-spec-capture: unknown arg '$($Rest[$i])'"; exit 1 }
         }
     }
@@ -1808,6 +1853,19 @@ function Invoke-FoundationRulesDone {
     Invoke-AwFoundationCore -Op 'rules-done' -Rest $fwd
 }
 
+# A pack's lane settings (<pack name>.lane.json). Twin of bash cmd_foundation_pack_lane.
+function Invoke-FoundationPackLane {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--name','--app' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            default { Write-Error "foundation-pack-lane: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwFoundationCore -Op 'pack-lane' -Rest $fwd
+}
+
 # ─────────────────────────── foundation-verify ─────────────────────────────
 function Invoke-FoundationVerify {
     param([string[]]$Rest)
@@ -4598,6 +4656,10 @@ switch ($sub) {
     'lane-resolve'     { Invoke-LaneResolve      -Rest $rest }
     'lane-verify'      { Invoke-LaneVerify       -Rest $rest }
     'lane-probe'       { Invoke-LaneProbe        -Rest $rest }
+    'lane-set'         { Invoke-LaneSet          -Rest $rest }
+    'contract-export'  { Invoke-ContractExport   -Rest $rest }
+    'contract-client'  { Invoke-ContractClient   -Rest $rest }
+    'contract-check'   { Invoke-ContractCheck    -Rest $rest }
     'list-contexts'    { Invoke-ListContexts     -Rest $rest }
     'set-context'      { Invoke-SetContext       -Rest $rest }
     'list-features'    { Invoke-ListFeatures     -Rest $rest }
@@ -4652,6 +4714,7 @@ switch ($sub) {
     'foundation-verify' { Invoke-FoundationVerify -Rest $rest }
     'foundation-rules' { Invoke-FoundationRules -Rest $rest }
     'foundation-rules-done' { Invoke-FoundationRulesDone -Rest $rest }
+    'foundation-pack-lane' { Invoke-FoundationPackLane -Rest $rest }
     'list-components'  { Invoke-ListComponents   -Rest $rest }
     'component-catalog' { Invoke-ComponentCatalog -Rest $rest }
     'component-verify' { Invoke-ComponentVerify   -Rest $rest }

package/assets/.appweaver/scripts/python/aw-foundation.py

@@ -64,7 +64,9 @@ Usage:
   aw-foundation.py choice --selection <option|name|n> [same filters as list]
       -> {"ok": bool, "route": "pack|spec|manual|skip", "name": "...", "file": "...", ...}
   aw-foundation.py spec-capture --lane <id> [--kind <k>] (--file <path> | --input <path|text>)
-      -> {"ok": bool, "spec_path": ".appweaver/foundation/<id>.spec.md", "source": "...", ...}
+                                [--app <App>]
+      -> {"ok": bool, "spec_path": ".appweaver/foundation/<id>.spec.md", "source": "...",
+          "contract_run": "...", "contract": "...", "client": "...", "settings_text": "...", ...}
   aw-foundation.py lane-files --source <path> [--test <path>] [--workdir <path>] [--profile <id>]
       -> {"has_files": bool, "count": n, "sample": [...], "generated": [...],
           "root_files": [...], "folders": [...], "workdir": "...", "summary": "...",
@@ -80,6 +82,12 @@ Usage:
           "merges": [{"target", "existing", "instruction", "rule"}], "merge_count": n,
           "stale": [...], "note": "..."}
   aw-foundation.py rules-done [--state <repo-relative folder>]  -> {"ok": true, "removed": bool}
+  aw-foundation.py pack-lane --name <Foundation> --app <App>
+      -> {"found": bool, "file": "...", "contract_run": "...", "contract": "...",
+          "client": "...", "reason": "..."}
+
+A pack may also carry LANE SETTINGS, `<pack name>.lane.json` beside it: values the lane
+records in stacks.json once the pack is unpacked (see pack_lane).
 """
 
 import argparse
@@ -196,8 +204,10 @@ def redirect_tests(repo, out, test_path, force=False):
 LABEL_SEP = "  — "
 MANUAL = "[manual spec]"
 SKIP = "[skip]"
-HEADER_KEYS = ("kind", "profiles", "title", "foundation", "sentinel", "files")
-HEADER_RE = re.compile(r"^#\s*([a-z_]+)\s*:\s*(.*?)\s*$")
+HEADER_KEYS = ("kind", "profiles", "title", "foundation", "sentinel", "files",
+               "contract_run", "contract", "client")
+# A key may be written with hyphens (`contract-run`); it is read as the underscored name.
+HEADER_RE = re.compile(r"^#\s*([a-z][a-z_-]*)\s*:\s*(.*?)\s*$")
 
 
 HEADER_LINES = 40
@@ -219,8 +229,9 @@ def read_header_text(text):
         if not s.startswith("#"):
             break
         m = HEADER_RE.match(s)
-        if m and m.group(1) in HEADER_KEYS and m.group(1) not in head:
-            head[m.group(1)] = m.group(2)
+        key = m.group(1).replace("-", "_") if m else ""
+        if key in HEADER_KEYS and key not in head:
+            head[key] = m.group(2)
     return head
 
 
@@ -386,7 +397,11 @@ def resolve_choice(repo, selection, kind="", profile="", ecosystems=None):
 SPEC_LIMIT = 200_000
 
 
-def capture_spec(repo, lane, kind="", file="", text=""):
+SETTING_LABELS = (("contract_run", "start command"), ("contract", "document URL"),
+                  ("client", "client command"))
+
+
+def capture_spec(repo, lane, kind="", file="", text="", app=""):
     """Copy the spec a lane is being built from to .appweaver/foundation/<lane>.spec.md.
 
     The copy is the record of what the project was built from: a bundle spec can change
@@ -394,10 +409,17 @@ def capture_spec(repo, lane, kind="", file="", text=""):
     it names a file, and as the spec itself otherwise — except a single word that is
     shaped like a path (a separator, or a file extension), which is a path that was
     mistyped: capturing it as a fifteen-character spec would build a project from it.
+
+    Also returns the lane settings the spec's header gives — `# contract-run:`,
+    `# contract:` and `# client:`, with `<App>` replaced by `app` — which foundation
+    records on the lane once the project is built. They are read here, from the spec as
+    given, because the copy opens with a comment and has no header left to read.
     """
     def fail(why):
-        return {"ok": False, "spec_path": "", "source": "", "chars": 0, "title": "",
-                "reason": why}
+        out = {"ok": False, "spec_path": "", "source": "", "chars": 0, "title": "",
+               "reason": why, "settings_text": "none", "placeholder": "{{contract}}"}
+        out.update({k: "" for k in LANE_KEYS})
+        return out
 
     source, body = "", ""
     cand = (file or "").strip()
@@ -427,7 +449,8 @@ def capture_spec(repo, lane, kind="", file="", text=""):
     if not body.strip():
         return fail("no spec was given — enter a file path or the spec text")
 
-    title = read_header_text(body).get("title", "")
+    head = read_header_text(body)
+    title = head.get("title", "")
     if not title:
         for line in body.splitlines():
             s = line.strip()
@@ -445,8 +468,17 @@ def capture_spec(repo, lane, kind="", file="", text=""):
                  "     source: %s · captured %s -->\n\n"
                  % ((kind + " lane") if kind else "lane", lane_slug, source, stamp))
         fh.write(body if body.endswith("\n") else body + "\n")
-    return {"ok": True, "spec_path": rel, "source": source, "chars": len(body),
-            "title": title, "reason": ""}
+    settings = {k: head.get(k, "").replace("<App>", app) if app else head.get(k, "")
+                for k in LANE_KEYS}
+    text_parts = ["%s `%s`" % (label, settings[k]) for k, label in SETTING_LABELS if settings[k]]
+    out = {"ok": True, "spec_path": rel, "source": source, "chars": len(body),
+           "title": title, "reason": "",
+           # One line for a prompt, and the placeholder a client command names the API
+           # document by, spelled out — a workflow cannot write it literally.
+           "settings_text": "; ".join(text_parts) or "none",
+           "placeholder": "{{contract}}"}
+    out.update(settings)
+    return out
 
 
 # ───────────────────────────── what a lane already holds ─────────────────────────────
@@ -854,6 +886,44 @@ def pack_rules(repo, name, app, out, reference=False, state=MERGE_STATE):
                 note="".join("; " + p for p in parts))
 
 
+LANE_FORMAT = "aw-spec-pack-lane/v1"
+LANE_KEYS = ("contract_run", "contract", "client")
+
+
+def pack_lane(repo, name, app):
+    """The lane settings a pack carries in `<pack name>.lane.json` beside it, with the
+    sentinel renamed as in the pack's own files.
+
+    These are what only the pack knows about the project it scaffolds — chiefly how to
+    start its service on its own to export the API document, which for a solution with
+    an orchestration host is not the lane's `run` command. A pack with no such file has
+    nothing to add, and the lane keeps its stack profile's values.
+
+      {"format": "aw-spec-pack-lane/v1",
+       "contract_run": "dotnet run --project src/<Sentinel>.Service -- --urls http://localhost:5000",
+       "contract": "http://localhost:5000/swagger/v1/swagger.json"}
+    """
+    pack = _pack_path(repo, name)
+    result = {"found": False, "file": "", "reason": ""}
+    result.update({k: "" for k in LANE_KEYS})
+    if not pack:
+        return dict(result, reason="the %s pack was not found" % name)
+    rel = pack[:-len(".pack.txt")] + ".lane.json"
+    path = os.path.join(repo, rel)
+    if not os.path.isfile(path):
+        return dict(result, reason="the %s pack carries no lane settings (%s)" % (name, rel))
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (ValueError, OSError) as e:
+        return dict(result, file=rel, reason="%s cannot be read (%s)" % (rel, e))
+    if not isinstance(data, dict) or data.get("format", LANE_FORMAT) != LANE_FORMAT:
+        return dict(result, file=rel, reason='%s is not an "%s" file' % (rel, LANE_FORMAT))
+    forms = _rename_forms(read_header(os.path.join(repo, pack)).get("sentinel", ""), app)
+    values = {k: _renamed(str(data.get(k) or "").strip(), forms) for k in LANE_KEYS}
+    return dict(result, found=any(values.values()), file=rel, **values)
+
+
 def rules_done(repo, state=MERGE_STATE):
     """Remove the files `rules` put aside, once the merges have read them."""
     stash = _state_dir(state)
@@ -894,6 +964,7 @@ def main():
     sc.add_argument("--kind", default="")
     sc.add_argument("--file", default="")
     sc.add_argument("--input", default="")
+    sc.add_argument("--app", default="", help="the app name `<App>` in the header stands for")
     lf = sub.add_parser("lane-files")
     lf.add_argument("--source", default="", help="the lane root folder")
     lf.add_argument("--test", default="", help="the lane's test path")
@@ -913,6 +984,9 @@ def main():
     ru.add_argument("--state", default=MERGE_STATE, help="where existing files are put aside")
     rd = sub.add_parser("rules-done")
     rd.add_argument("--state", default=MERGE_STATE)
+    pl = sub.add_parser("pack-lane")
+    pl.add_argument("--name", required=True, help="the foundation")
+    pl.add_argument("--app", required=True, help="the app name the sentinel is renamed to")
     args = ap.parse_args()
 
     if args.cmd == "redirect-tests":
@@ -923,7 +997,7 @@ def main():
     elif args.cmd == "choice":
         emit(resolve_choice(args.repo, args.selection, args.kind, args.profile, args.ecosystem))
     elif args.cmd == "spec-capture":
-        emit(capture_spec(args.repo, args.lane, args.kind, args.file, args.input))
+        emit(capture_spec(args.repo, args.lane, args.kind, args.file, args.input, args.app))
     elif args.cmd == "lane-files":
         emit(lane_files(args.repo, args.source, args.test, args.workdir, args.profile))
     elif args.cmd == "snapshot":
@@ -934,6 +1008,8 @@ def main():
         emit(pack_rules(args.repo, args.name, args.app, args.out, args.reference, args.state))
     elif args.cmd == "rules-done":
         emit(rules_done(args.repo, args.state))
+    elif args.cmd == "pack-lane":
+        emit(pack_lane(args.repo, args.name, args.app))
 
 
 if __name__ == "__main__":