aw-spec-cli 0.1.26 → 0.1.28

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

@@ -3,7 +3,7 @@
 # aw-spec-actions.ps1 — common action dispatcher for the aw-spec orchestrator
 # (Windows / PowerShell mirror of aw-spec-actions.sh).
 #
-# ONE shared script for every integration (.claude / .agents / .kilocode). The
+# ONE shared script for every integration (.claude / .agents / .kilo). The
 # orchestrator workflows reach these subcommands through `execute_script` steps.
 # Each subcommand performs deterministic, governance-safe work and prints a single
 # JSON object on stdout. NONE of these actions author spec/code content — content
@@ -107,7 +107,7 @@ function Invoke-ResolveDomain {
         try { $domain = (Get-Content $domainJson -Raw | ConvertFrom-Json).domain } catch { $domain = '' }
         if (-not $domain) { $domain = '' }
     }
-    $rulemap = Join-Path $repo "guardrails/projects/$domain/domain-rule-bindings.md"
+    $rulemap = Join-Path $repo "guardrails/$domain/domain-rule-bindings.md"
     $rulemapExists = ($domain -ne '') -and (Test-Path $rulemap)
 
     $candidates = @()
@@ -132,7 +132,7 @@ function Invoke-ResolveDomain {
 
 # ─────────────────────────── resolve-tech ───────────────────────────────────
 # Technical rule-file mapping — parallel to resolve-domain, but reads
-# guardrails/projects/<project>/tech-rule-bindings.md. The TECHNICAL rule files live in the
+# guardrails/<project>/tech-rule-bindings.md. The TECHNICAL rule files live in the
 # shared per-stack corpora at guardrails/technology/<stack>/ (rules) and
 # guardrails/technology/<stack>/examples/ (the worked sample for a rule file), and are
 # configured per-command in this map, so they can be tuned per project WITHOUT editing the
@@ -162,7 +162,7 @@ function Invoke-ResolveTech {
         try { $domain = (Get-Content $domainJson -Raw | ConvertFrom-Json).domain } catch { $domain = '' }
         if (-not $domain) { $domain = '' }
     }
-    $techmap = Join-Path $repo "guardrails/projects/$domain/tech-rule-bindings.md"
+    $techmap = Join-Path $repo "guardrails/$domain/tech-rule-bindings.md"
     $techmapExists = ($domain -ne '') -and (Test-Path $techmap)
 
     # The declared stacks, so one map can be written for any of them.
@@ -512,15 +512,16 @@ function Invoke-CreateChecklist {
 }
 
 # ─────────────────────────── list-domains ──────────────────────────────────
-# The selectable projects: immediate subdirs of guardrails/projects/ that carry a rule
-# map. The map is what makes a directory a project, exactly as a *.pack.txt is what makes
-# a foundations/ directory a foundation — without that test any stray sibling would be
-# offered as a governance target. EITHER map qualifies, because onboard writes the domain
-# map several steps before the technical one and a half-built project must stay visible.
+# The projects: immediate subdirs of guardrails/ that carry a rule map. The map is what
+# makes a directory a project, exactly as a *.pack.txt is what makes a foundations/
+# directory a foundation — the shared corpora technology/ and domain/ sit beside the
+# projects and carry no map, so they are never listed. EITHER map qualifies, because
+# onboard writes the domain map several steps before the technical one and a half-built
+# project must stay visible.
 function Invoke-ListDomains {
     param([string[]]$Rest)
     $repo = Get-RepoRoot
-    $base = Join-Path $repo 'guardrails/projects'
+    $base = Join-Path $repo 'guardrails'
     $domains = @()
     if (Test-Path $base) {
         $domains = @(Get-ChildItem -Directory $base -ErrorAction SilentlyContinue | Where-Object {
@@ -541,7 +542,7 @@ function Invoke-SetDomain {
     if (-not $domain) { Write-Error 'set-domain: --domain is required'; exit 1 }
 
     $repo = Get-RepoRoot
-    $mapRel = "guardrails/projects/$domain/domain-rule-bindings.md"
+    $mapRel = "guardrails/$domain/domain-rule-bindings.md"
     $mapExists = Test-Path (Join-Path $repo $mapRel)
 
     New-Item -ItemType Directory -Force -Path (Join-Path $repo '.appweaver') | Out-Null
@@ -562,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
@@ -640,9 +640,55 @@ 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 source path is declared
+# --allow-missing-root is the greenfield state, where a lane root folder is declared
 # before implement creates it.
 function Invoke-LaneVerify {
     param([string[]]$Rest)
@@ -811,6 +857,9 @@ function Invoke-ListContexts {
 # Twin of bash cmd_set_context. Creates the context directory but NOT
 # domain-model.md — specify is the only writer of the model, and an empty
 # placeholder would read as "the model exists" to every later gate.
+# Clears .appweaver/feature.json when the selected context does not contain the
+# active feature (a flat specs/<Feature> included), so no feature-scoped command
+# writes into the context the developer just left.
 function Invoke-SetContext {
     param([string[]]$Rest)
     $raw = ''
@@ -840,6 +889,18 @@ function Invoke-SetContext {
     [ordered]@{ context = $context; context_directory = $contextDirRel } | ConvertTo-Json -Compress |
         Set-Content -Path (Join-Path $repo '.appweaver/context.json') -Encoding UTF8
 
+    $activeFd = "$(Read-FeatureDir -RepoRoot $repo)" -replace '\\', '/'
+    $repoPrefix = ($repo -replace '\\', '/').TrimEnd('/') + '/'
+    if ($activeFd.StartsWith($repoPrefix, [System.StringComparison]::Ordinal)) { $activeFd = $activeFd.Substring($repoPrefix.Length) }
+    if ($activeFd.StartsWith('./', [System.StringComparison]::Ordinal)) { $activeFd = $activeFd.Substring(2) }
+    $activeFd = $activeFd.TrimEnd('/')
+    $featureCleared = $false; $clearedFeature = ''
+    if ($activeFd -and -not $activeFd.StartsWith("$contextDirRel/", [System.StringComparison]::Ordinal)) {
+        @{ feature_directory = '' } | ConvertTo-Json -Compress |
+            Set-Content -Path (Join-Path $repo '.appweaver/feature.json') -Encoding UTF8
+        $featureCleared = $true; $clearedFeature = $activeFd
+    }
+
     Write-Json ([ordered]@{
         context             = $context
         context_dir         = $contextDirRel
@@ -847,6 +908,8 @@ function Invoke-SetContext {
         existed             = [bool]$existed
         created             = (-not $existed)
         domain_model_exists = (Test-Path (Join-Path $contextDir 'domain-model.md'))
+        feature_cleared     = $featureCleared
+        cleared_feature     = $clearedFeature
         written             = $true
     })
 }
@@ -1033,6 +1096,43 @@ function Invoke-SetFeature {
     })
 }
 
+# ─────────────────────────── default-scope ─────────────────────────────────
+# Twin of bash cmd_default_scope. Acts only on a project with no specs yet — no
+# directory under specs/ and no active feature — and creates through set-context and
+# set-feature, so both pointer files are written exactly as the select commands write
+# them. context_dir / feature_dir report the active pair after the call, created or not.
+function Invoke-DefaultScope {
+    param([string[]]$Rest)
+    $ctx = ''; $feat = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        if ($Rest[$i] -in '--context','-Context')     { $ctx  = $Rest[++$i] }
+        elseif ($Rest[$i] -in '--feature','-Feature') { $feat = $Rest[++$i] }
+    }
+    if (-not $ctx -or -not $feat) { Write-Error 'default-scope: --context and --feature are required'; exit 1 }
+
+    $repo = Get-RepoRoot
+    $specs = Join-Path $repo 'specs'
+    $reason = ''
+    if ((Test-Path $specs) -and @(Get-ChildItem -Directory -Force $specs -ErrorAction SilentlyContinue).Count -gt 0) {
+        $reason = 'specs/ already holds a bounded context or a feature'
+    } elseif ("$(Read-FeatureDir -RepoRoot $repo)") {
+        $reason = 'a feature is already active in .appweaver/feature.json'
+    }
+
+    $created = $false
+    if (-not $reason) {
+        $null = Invoke-SetContext -Rest @('--context', $ctx)
+        $null = Invoke-SetFeature -Rest @('--feature', $feat)
+        $created = $true
+    }
+    Write-Json ([ordered]@{
+        created        = $created
+        skipped_reason = $reason
+        context_dir    = "$(Get-ContextDirectory -Repo $repo)"
+        feature_dir    = "$(Read-FeatureDir -RepoRoot $repo)"
+    })
+}
+
 # ═══════════════════════════ active_version.json ════════════════════════════
 # Per-feature version state. Shells out to the SAME python as the bash twin so the
 # bump/timestamp logic is byte-identical across shells. (See bash _active_version.)
@@ -1483,7 +1583,7 @@ function Invoke-DetectProject {
     $repo = Get-RepoRoot
     $scope = 'repo'
     $start = $repo
-    # A lane's source path arrives as the value declare stored, so it may carry a
+    # A lane root folder arrives as the value declare stored, so it may carry a
     # trailing slash; an option label ("path  — why") never reaches a script argument.
     $rel = ($scopeRoot -replace '\\','/').TrimStart('.','/').TrimEnd('/')
     if ($rel -and (Test-Path -PathType Container (Join-Path $repo $rel))) {
@@ -1533,52 +1633,118 @@ function Get-FoundationDirs {
 }
 
 # ──────────────────────────── foundation-list ──────────────────────────────
-# List available foundations (foundations/<stack>/<Name>/ with a real <Name>.pack.txt)
-# for the user to PICK — deterministic, no LLM. Optional --args fast path mirrors bash,
-# including a third token coming back as `rejected_out` rather than as a destination:
-# see the bash twin for why a scaffold has no caller-chosen output directory.
+# What ONE lane can be scaffolded from, as a pick list: its packs and specs, then
+# "[manual spec]" and "[skip]". Twin of bash cmd_foundation_list — see it for the three
+# filters. Both delegate to aw-foundation.py, so the scan has one implementation.
+function Invoke-AwFoundationCore {
+    param([string]$Op, [string[]]$Rest)
+    $py = Get-Py
+    if (-not $py) { Write-Error 'aw-foundation: python3 is required to list foundations'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-foundation.py'
+    if (-not (Test-Path $core)) { Write-Error "aw-foundation: core not found at $core"; exit 1 }
+    $repo = Get-RepoRoot
+    & $py $core '--repo' $repo $Op @Rest
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
 function Invoke-FoundationList {
     param([string[]]$Rest)
-    $raw = ''; $ecoFilter = ''
-    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { '--args' { $raw = $Rest[++$i] } '--ecosystem' { $ecoFilter = $Rest[++$i] } } }
-    $repo = Get-RepoRoot
+    $fwd = @(); $ecoGiven = $false
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--args','--kind','--profile','--lane-id' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            '--ecosystem' { $fwd += '--ecosystem'; $fwd += $Rest[++$i]; $ecoGiven = $true }
+            default { Write-Error "foundation-list: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    # Without --ecosystem: every declared lane's ecosystem, and no filter on a bare repo.
+    if (-not $ecoGiven) { foreach ($e in @(Get-Ecosystems)) { $fwd += '--ecosystem'; $fwd += $e } }
+    Invoke-AwFoundationCore -Op 'list' -Rest $fwd
+}
 
-    # WHICH foundations this repo may be offered. A foundation bundle is a whole
-    # compiling project in one ecosystem's languages and build system, so unpacking a
-    # .NET one into a Spring repo does not produce a scaffold — it produces a second,
-    # foreign project beside the real one. --ecosystem narrows to the ONE lane being
-    # scaffolded; without it the filter is every declared lane's ecosystem, and nothing
-    # at all on a bare repo.
-    $laneEcos = if ($ecoFilter) { @($ecoFilter) } else { @(Get-Ecosystems) }
-    $foundations = @(); $all = @(); $ecoOf = @()
-    foreach ($f in @(Get-FoundationDirs $repo)) {
-        if (-not (Test-Path (Join-Path $f.Dir "$($f.Name).pack.txt"))) { continue }
-        $all += $f.Name; $ecoOf += $f.Stack
-        if ($laneEcos.Count -eq 0 -or $laneEcos -contains $f.Stack) { $foundations += $f.Name }
-    }
-    $preName = ''; $preApp = ''; $rejectedOut = ''
-    if ($raw) { $t = $raw -split '\s+' | Where-Object { $_ }; if ($t.Count -ge 1) { $preName = $t[0] }; if ($t.Count -ge 2) { $preApp = $t[1] }; if ($t.Count -ge 3) { $rejectedOut = $t[2] } }
-    $match = if ($foundations -contains $preName) { $preName } else { '' }
-    Write-Json ([ordered]@{
-        foundations = @($foundations); count = $foundations.Count
-        all_foundations = @($all); all_count = $all.Count
-        ecosystems = @($ecoOf); lane_ecosystems = @($laneEcos)
-        filtered = ($laneEcos.Count -gt 0)
-        preselect_name = $match; preselect_app = $preApp; rejected_out = $rejectedOut
-    })
+# ─────────────────────────── foundation-choice ─────────────────────────────
+# Resolve the picked option back to its entry (route, name, file). Twin of bash.
+function Invoke-FoundationChoice {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--selection','--kind','--profile','--ecosystem' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            default { Write-Error "foundation-choice: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwFoundationCore -Op 'choice' -Rest $fwd
+}
+
+# ────────────────────────── foundation-spec-capture ────────────────────────
+# Copy the spec a lane is about to be built from to .appweaver/foundation/<lane>.spec.md.
+# Twin of bash cmd_foundation_spec_capture.
+function Invoke-FoundationSpecCapture {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($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 }
+        }
+    }
+    Invoke-AwFoundationCore -Op 'spec-capture' -Rest $fwd
+}
+
+# ─────────────────────────── foundation-lane-files ─────────────────────────
+# What a lane already holds, asked before anything is scaffolded into it. Twin of
+# bash cmd_foundation_lane_files.
+function Invoke-FoundationLaneFiles {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--source','--test','--workdir','--profile' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            default { Write-Error "foundation-lane-files: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwFoundationCore -Op 'lane-files' -Rest $fwd
+}
+
+# ─────────────────────── foundation-snapshot / -outside ────────────────────
+# What a spec build did outside its lane root folder: `snapshot` records the repo before
+# the build, `outside` lists what changed elsewhere afterwards and, with --undo, removes
+# what was created. Twins of bash cmd_foundation_snapshot / cmd_foundation_outside.
+function Invoke-FoundationSnapshot {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--out' { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            default { Write-Error "foundation-snapshot: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwFoundationCore -Op 'snapshot' -Rest $fwd
+}
+
+function Invoke-FoundationOutside {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--snapshot','--lane' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            '--undo' { $fwd += $Rest[$i] }
+            default { Write-Error "foundation-outside: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwFoundationCore -Op 'outside' -Rest $fwd
 }
 
 function Invoke-FoundationLocate {
     param([string[]]$Rest)
-    $name = ''; $app = ''; $out = '.'; $raw = ''
-    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { '--name' { $name = $Rest[++$i] } '--app' { $app = $Rest[++$i] } '--out' { $out = $Rest[++$i] } '--args' { $raw = $Rest[++$i] } } }
-    if ($raw) { $t = $raw -split '\s+' | Where-Object { $_ }; if ($t.Count -ge 1) { $name = $t[0] }; if ($t.Count -ge 2) { $app = $t[1] }; if ($t.Count -ge 3) { $out = $t[2] } }
+    $name = ''; $app = ''; $out = '.'
+    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { '--name' { $name = $Rest[++$i] } '--app' { $app = $Rest[++$i] } '--out' { $out = $Rest[++$i] } } }
     $repo = Get-RepoRoot
     $dirs = @(Get-FoundationDirs $repo)
     # available = every foundation dir (Get-FoundationDirs already requires a *.pack.txt)
     $available = @($dirs | ForEach-Object { $_.Name })
     function _fail($r) { Write-Json ([ordered]@{ ok = $false; reason = $r; available = @($available) }) }
-    if (-not $name -or -not $app) { _fail 'Usage: /aw-spec-foundation <FoundationName> <AppName> [OutputDirectory]'; return }
+    if (-not $name -or -not $app) { _fail 'foundation-locate needs --name <FoundationName> and --app <AppName>'; return }
     $found = $dirs | Where-Object { $_.Name -eq $name } | Select-Object -First 1
     if (-not $found) { _fail "Foundation '$name' not found (expected foundations/<stack>/$name/)"; return }
     $stack = $found.Stack; $rel = $found.Rel; $fdir = $found.Dir
@@ -1593,15 +1759,17 @@ function Invoke-FoundationLocate {
     $sm = [regex]::Match($header, '(?i)sentinel[^A-Za-z0-9_.]*([A-Za-z0-9_.]+)')
     if ($sm.Success) { $sentinel = $sm.Groups[1].Value }
     $fc = 0; $fm = [regex]::Match($header, '(?i)file[^0-9]*([0-9]+)'); if ($fm.Success) { $fc = [int]$fm.Groups[1].Value }
+    # A reference sample is offered only when its pack is there to unpack.
+    $hasReference = Test-Path (Join-Path $fdir "$name.Reference.pack.txt")
     Write-Json ([ordered]@{
         ok = $true; reason = ''; name = $name; stack = $stack; app = $app; out_dir = $out
         pack_file = "$rel/$name.pack.txt"; unpacker = $unpacker; runner = $runner
-        sentinel = $sentinel; file_count = $fc; available = @($available)
+        sentinel = $sentinel; file_count = $fc; has_reference = $hasReference; available = @($available)
     })
 }
 
 # ─────────────────────────── foundation-unpack ─────────────────────────────
-# --out is the LANE'S SOURCE PATH and --test-path its other subtree; the pack's own test
+# --out is the LANE ROOT FOLDER and --test-path its other subtree; the pack's own test
 # tree is lifted onto the latter by aw-foundation.py. Twin of the bash cmd_foundation_unpack
 # — see it for why a scaffold goes into a lane rather than into the repo root.
 function Invoke-FoundationUnpack {
@@ -1613,11 +1781,11 @@ function Invoke-FoundationUnpack {
     if (-not $name -or -not $app) { Write-Error 'foundation-unpack: --name and --app required'; exit 1 }
     $repo = Get-RepoRoot
     $found = @(Get-FoundationDirs $repo) | Where-Object { $_.Name -eq $name } | Select-Object -First 1
-    $fdir = if ($found) { $found.Dir } else { Join-Path $repo "foundations/$name" }
     $packbase = if ($reference) { "$name.Reference" } else { $name }
     $stem = if ($reference) { 'unpack-reference-foundation' } else { 'unpack-foundation' }
-    $pack = Join-Path $fdir "$packbase.pack.txt"
-    if (-not (Test-Path $pack)) { Write-Json ([ordered]@{ ok = $false; mode = $(if ($dry) { 'dry' } else { 'real' }); written = 0; has_collisions = $false; stdout = "pack not found: $packbase.pack.txt" }); return }
+    $pack = if ($found) { Join-Path $found.Dir "$packbase.pack.txt" } else { '' }
+    $fdir = if ($found) { $found.Dir } else { '' }
+    if (-not $pack -or -not (Test-Path $pack)) { Write-Json ([ordered]@{ ok = $false; mode = $(if ($dry) { 'dry' } else { 'real' }); written = 0; has_collisions = $false; stdout = "pack not found: $packbase.pack.txt" }); return }
     $cmd = $null; $cargs = @()
     if ((Get-Command pwsh -ErrorAction SilentlyContinue) -and (Test-Path (Join-Path $fdir "$stem.ps1"))) {
         $cmd = 'pwsh'; $cargs = @('-NoProfile','-File',(Join-Path $fdir "$stem.ps1"),'-PackFile',$pack,'-TargetAppName',$app,'-OutDir',$out)
@@ -1657,20 +1825,45 @@ function Invoke-FoundationUnpack {
     Write-Json ([ordered]@{ ok = ($rc -eq 0); mode = $(if ($dry) { 'dry' } else { 'real' }); written = $written; has_collisions = $hasColl; tests_moved = $testsMoved; tests_message = $testsMsg; stdout = ($outp.Substring([Math]::Max(0,$outp.Length-800))) })
 }
 
-# ─────────────────────── foundation-stash-dbcontext ────────────────────────
-function Invoke-FoundationStashDbContext {
+# ───────────────────── foundation-rules / -rules-done ──────────────────────
+# What a pack's rule file (<pack name>.rules.json) asks of an unpack, and the clean-up
+# after its merges. Twins of bash cmd_foundation_rules / cmd_foundation_rules_done.
+function Invoke-FoundationRules {
     param([string[]]$Rest)
-    $out = '.'
-    for ($i = 0; $i -lt $Rest.Count; $i++) { if ($Rest[$i] -eq '--out') { $out = $Rest[++$i] } }
-    $repo = Get-RepoRoot
-    if (-not [System.IO.Path]::IsPathRooted($out)) { $out = Join-Path $repo $out }
-    # Searched from the unpack root itself, which IS the lane's source path — a `src/`
-    # segment underneath it is the old repo-root layout and is not there any more.
-    $ctx = Get-ChildItem -LiteralPath $out -Recurse -Filter 'ApplicationDbContext.cs' -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
-    if (-not $ctx) { Write-Json ([ordered]@{ found = $false; dbcontext = ''; backup = '' }); return }
-    $bak = "$ctx.foundation.bak"
-    Copy-Item $ctx $bak
-    Write-Json ([ordered]@{ found = $true; dbcontext = $ctx; backup = $bak })
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--name','--app','--out','--state' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            '--reference' { $fwd += $Rest[$i] }
+            default { Write-Error "foundation-rules: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwFoundationCore -Op 'rules' -Rest $fwd
+}
+
+function Invoke-FoundationRulesDone {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--state' { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            default { Write-Error "foundation-rules-done: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    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 ─────────────────────────────
@@ -2144,7 +2337,7 @@ function Invoke-ListComponents {
 function Invoke-FindHostProject {
     param([string[]]$Rest)
     $repo = Get-RepoRoot
-    # WHERE the host lives. The service lane's declared source path when there is one,
+    # WHERE the host lives. The declared lane root folder of the service lane when there is one,
     # 'src' when there is not — the same question run-migrate asks, and the same answer.
     $svcRoot = Get-LaneField -Field 'backend_root'
     if (-not $svcRoot) { $svcRoot = 'src' }
@@ -2461,13 +2654,25 @@ function Get-Ecosystems {
 function Invoke-BuildCompile {
     param([string[]]$Rest)
     $repo = Get-RepoRoot
+    # --kind builds ONE declared lane — what `foundation` uses to check the lane it just
+    # created without compiling a lane it did not touch. Ignored on the undeclared ladder.
+    $kind = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--feature-dir' { $i++ }
+            '--kind'        { $kind = $Rest[++$i] }
+            default { Write-Error "build-compile: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
 
     # A DECLARED lane model is the answer, and it is a better answer than the ladder
     # below in exactly the case that matters: a repo with two lanes. The sniffer takes
     # the first toolchain it finds and silently never builds the second, which reports
     # green for a frontend that was never compiled.
     if ((Get-LaneField -Field 'lane_count') -and (Get-LaneField -Field 'lane_count') -ne '0') {
-        Invoke-AwStackCore -Op 'run-phase' -Rest @('--phase', 'build')
+        $phaseArgs = @('--phase', 'build')
+        if ($kind) { $phaseArgs += @('--kind', $kind) }
+        Invoke-AwStackCore -Op 'run-phase' -Rest $phaseArgs
         return
     }
 
@@ -2673,7 +2878,7 @@ function Invoke-RunMigrate {
         return
     }
 
-    # WHERE to look for the migration project. The service lane's declared source path
+    # WHERE to look for the migration project. The declared lane root folder of the service lane
     # when there is one, 'src' when there is not. Migrations belong to the backend lane
     # by definition, so a repo whose service code sits in 'Legacy/App/' or 'backend/'
     # gets searched where its code actually is instead of being told it has no .NET
@@ -2691,7 +2896,7 @@ function Invoke-RunMigrate {
     }
     if ($efOk) {
         # Prefer *Service.csproj (API host with ApplicationDbContext); fall back to first
-        # non-AppHost/Web/ServiceDefaults/test project under the service lane's root.
+        # non-AppHost/Web/ServiceDefaults/test project under the service lane root folder.
         $project = Get-ChildItem -LiteralPath $svcDir -Filter '*.Service.csproj' -Recurse -ErrorAction SilentlyContinue |
             Select-Object -First 1 -ExpandProperty FullName
         if (-not $project) {
@@ -4451,10 +4656,15 @@ 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 }
     'set-feature'      { Invoke-SetFeature       -Rest $rest }
+    'default-scope'    { Invoke-DefaultScope     -Rest $rest }
     'version-read'     { Invoke-VersionState 'read'  $rest }
     'version-init'     { Invoke-VersionState 'init'  $rest }
     'version-bootstrap-done' { Invoke-VersionState 'bootstrap-done' $rest }
@@ -4494,10 +4704,17 @@ switch ($sub) {
     'checklist-apply'  { Invoke-ChecklistApply   -Rest $rest }
     'detect-project'   { Invoke-DetectProject    -Rest $rest }
     'foundation-list'  { Invoke-FoundationList   -Rest $rest }
+    'foundation-choice' { Invoke-FoundationChoice -Rest $rest }
+    'foundation-spec-capture' { Invoke-FoundationSpecCapture -Rest $rest }
+    'foundation-lane-files' { Invoke-FoundationLaneFiles -Rest $rest }
+    'foundation-snapshot' { Invoke-FoundationSnapshot -Rest $rest }
+    'foundation-outside' { Invoke-FoundationOutside -Rest $rest }
     'foundation-locate' { Invoke-FoundationLocate -Rest $rest }
     'foundation-unpack' { Invoke-FoundationUnpack -Rest $rest }
     'foundation-verify' { Invoke-FoundationVerify -Rest $rest }
-    'foundation-stash-dbcontext' { Invoke-FoundationStashDbContext -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 }