aw-spec-cli 0.1.20 → 0.1.22

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

@@ -586,6 +586,7 @@ function Invoke-StackList {
         switch ($Rest[$i]) {
             '--kind'          { $fwd += '--kind'; $fwd += $Rest[++$i] }
             '--preselect'     { $fwd += '--preselect'; $fwd += $Rest[++$i] }
+            '--profile'       { $fwd += '--profile'; $fwd += $Rest[++$i] }
             '--include-none'  { $fwd += '--include-none' }
             '--suggest'       { $fwd += '--suggest' }
             default { Write-Error "stack-list: unknown arg '$($Rest[$i])'"; exit 1 }
@@ -1469,36 +1470,37 @@ 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.
+# 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.
 function Invoke-FoundationList {
     param([string[]]$Rest)
-    $raw = ''
-    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { '--args' { $raw = $Rest[++$i] } } }
+    $raw = ''; $ecoFilter = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { '--args' { $raw = $Rest[++$i] } '--ecosystem' { $ecoFilter = $Rest[++$i] } } }
     $repo = Get-RepoRoot
 
     # 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. The declared lanes already say which
-    # ecosystems this repo is, so filter to those and let the gate say why when that
-    # leaves nothing. Nothing declared (a bare greenfield repo, before select-stack)
-    # filters nothing: there is no answer yet to filter on.
-    $laneEcos = @(Get-Ecosystems)
+    # 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 = ''; $outDir = '.'
-    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) { $outDir = $t[2] } }
+    $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; out_dir = $outDir
+        preselect_name = $match; preselect_app = $preApp; rejected_out = $rejectedOut
     })
 }
 
@@ -1535,11 +1537,14 @@ function Invoke-FoundationLocate {
 }
 
 # ─────────────────────────── foundation-unpack ─────────────────────────────
+# --out is the LANE'S SOURCE PATH 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 {
     param([string[]]$Rest)
-    $name = ''; $app = ''; $out = '.'; $dry = $false; $force = 'no'; $reference = $false
+    $name = ''; $app = ''; $out = '.'; $dry = $false; $force = 'no'; $reference = $false; $testPath = ''
     for ($i = 0; $i -lt $Rest.Count; $i++) {
-        switch ($Rest[$i]) { '--name' { $name = $Rest[++$i] } '--app' { $app = $Rest[++$i] } '--out' { $out = $Rest[++$i] } '--dry-run' { $dry = $true } '--force' { $force = $Rest[++$i] } '--reference' { $reference = $true } }
+        switch ($Rest[$i]) { '--name' { $name = $Rest[++$i] } '--app' { $app = $Rest[++$i] } '--out' { $out = $Rest[++$i] } '--test-path' { $testPath = $Rest[++$i] } '--dry-run' { $dry = $true } '--force' { $force = $Rest[++$i] } '--reference' { $reference = $true } }
     }
     if (-not $name -or -not $app) { Write-Error 'foundation-unpack: --name and --app required'; exit 1 }
     $repo = Get-RepoRoot
@@ -1564,7 +1569,28 @@ function Invoke-FoundationUnpack {
     # unpackers say "Unpacked N file(s) to …" / "DryRun: N file(s) would be written …"
     $written = 0; $wm = [regex]::Match($outp, '(?i)([0-9]+)\s+file'); if ($wm.Success) { $written = [int]$wm.Groups[1].Value }
     $hasColl = ($dry -and $rc -ne 0)
-    Write-Json ([ordered]@{ ok = ($rc -eq 0); mode = $(if ($dry) { 'dry' } else { 'real' }); written = $written; has_collisions = $hasColl; stdout = ($outp.Substring([Math]::Max(0,$outp.Length-800))) })
+
+    # Put the pack's test tree on the lane's test path. Only after a REAL unpack that
+    # worked: a dry run has written nothing to lift, and a failed one leaves a tree
+    # nobody should be rearranging.
+    $testsMoved = 0; $testsMsg = ''
+    if (-not $dry -and $rc -eq 0 -and $testPath) {
+        $awFnd = Join-Path $PSScriptRoot '..' 'python' 'aw-foundation.py'
+        $py = Get-Py
+        if ($py -and (Test-Path $awFnd)) {
+            $rargs = @($awFnd, '--repo', $repo, 'redirect-tests', '--out', $out, '--test-path', $testPath)
+            if ($force -eq 'yes' -or $reference) { $rargs += '--force' }
+            $rout = (& $py @rargs 2>$null | Select-Object -Last 1)
+            if ($rout) {
+                try {
+                    $rj = $rout | ConvertFrom-Json
+                    $testsMoved = [int]$rj.moved; $testsMsg = [string]$rj.message
+                } catch { $testsMoved = 0; $testsMsg = '' }
+            }
+        }
+    }
+
+    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 ────────────────────────
@@ -1574,7 +1600,9 @@ function Invoke-FoundationStashDbContext {
     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 }
-    $ctx = Get-ChildItem -LiteralPath (Join-Path $out 'src') -Recurse -Filter 'ApplicationDbContext.cs' -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
+    # 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
@@ -1918,6 +1946,21 @@ function Get-LabeledVersion {
     }
     if ($vals.Count -gt 0) { return $vals[-1] } else { return $null }
 }
+
+# The ratified NON-NEGOTIABLE principles. A thin wrapper: the scan lives in
+# python/aw-principles.py, which BOTH shells invoke, so the list a gate cites cannot
+# differ between them. Defaults to the two halves specify loads; --file overrides.
+function Invoke-PrinciplesList {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $py = Get-Py
+    if (-not $py) { Write-Error 'principles-list: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-principles.py'
+    if (-not (Test-Path $core)) { Write-Error "principles-list: core not found at $core"; exit 1 }
+    & $py $core list --root $repo @Rest
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
 function Invoke-ConstitutionVerify {
     param([string[]]$Rest)
     $file = ''; $template = ''
@@ -2304,7 +2347,12 @@ function Invoke-DeltaPlanScaffold {
         if ($tpl -and (Test-Path $tpl)) { Copy-Item $tpl $target } else { New-Item -ItemType File -Force -Path $target | Out-Null }
         $created = $true
     }
-    Set-HeaderStamp -Path $target -Name 'Wave' -Value (Get-WaveOf -FeatureDir $fd -CrId $crId -Repo $repo)
+    # The lane plan carries the change's wave so a reader of the plan alone can see where it
+    # sits. It is COPIED from the delta-spec, never decided here — so when the spec has no
+    # readable wave the template's `[N]` is left standing, which is what the merge and recall
+    # fences read as "not ordered yet" and refuse on, with the command that stamps it.
+    $scaffoldWave = Get-WaveOfReadable -FeatureDir $fd -CrId $crId -Repo $repo
+    if ($scaffoldWave) { Set-HeaderStamp -Path $target -Name 'Wave' -Value $scaffoldWave }
     $overrideActive = Test-Path (Join-Path $repo (".appweaver/templates/overrides/" + $tplName + ".md"))
     $templateSource = Resolve-NamedTemplate -Name $tplName -RepoRoot $repo
     $tsOut = if ($templateSource) { $templateSource } else { '' }
@@ -2390,7 +2438,8 @@ function Invoke-TestRun {
         switch ($Rest[$i]) {
             { $_ -in '--feature-dir','-FeatureDir' } { $featureDir = $Rest[++$i] }
             { $_ -in '--scope','-Scope' }            { $scope = $Rest[++$i] }
-            { $_ -in '--also','-Also' }              { $also = $Rest[++$i] }
+            # Repeatable, lists UNION — see the bash twin for why the caller passes two.
+            { $_ -in '--also','-Also' }              { $v = $Rest[++$i]; $also = if ($also) { "$also,$v" } else { $v } }
         }
     }
     $repo = Get-RepoRoot
@@ -2413,6 +2462,9 @@ function Invoke-TestRun {
 
     $tool = 'none'; $ran = $false; $ok = $true; $cmd = ''; $log = ''
     $matched = $false; $scoped = $false; $fenceGreen = $false; $filter = ''
+    # The runner's exit code, kept because 126/127 is every shell's way of saying the
+    # command itself could not be executed — a missing runner, not a failing suite.
+    $rc = 0
     $hasSln = @(Get-ChildItem -LiteralPath $repo -Filter *.sln -File -ErrorAction SilentlyContinue).Count -gt 0
     $hasCsproj = @(Get-ChildItem -LiteralPath $repo -Filter *.csproj -Recurse -ErrorAction SilentlyContinue).Count -gt 0
     $dotnetPresent = ($hasSln -or $hasCsproj)
@@ -2450,6 +2502,16 @@ function Invoke-TestRun {
             fence_green = $dOk
             cmd         = $(if ($d -and $d.cmd) { [string]$d.cmd } else { '' })
             log_tail    = $dLog
+            # The failing lines of EVERY failing lane, budgeted per lane by run-phase —
+            # what the fix loop reads, in place of a tail that may belong to a lane that
+            # passed. Twin of the bash branch.
+            failing_excerpt = $(if ($d -and $d.failing_excerpt) { [string]$d.failing_excerpt } else { '' })
+            failing_lanes   = @(if ($d -and $d.failing_lanes) { $d.failing_lanes } else { @() })
+            # NOTHING ran a suite because no lane's test command is wired up — a different
+            # state from a red suite, and the one a fix loop cannot help with.
+            no_setup        = [bool]($d -and $d.no_setup)
+            setup_reason    = $(if ($d -and $d.setup_reason) { [string]$d.setup_reason } else { '' })
+            setup_missing   = @(if ($d -and $d.setup_missing) { $d.setup_missing } else { @() })
             lanes_run     = @(if ($d) { $d.lanes_run } else { @() })
             lanes_skipped = @(if ($d) { $d.lanes_skipped } else { @() })
         })
@@ -2468,16 +2530,16 @@ function Invoke-TestRun {
                 } else {
                     $filter = ($slices | ForEach-Object { "FullyQualifiedName~$_" }) -join '|'
                     $scoped = $true; $cmd = "dotnet test --nologo --filter `"$filter`""; $ran = $true
-                    Push-Location $repo; try { $log = (dotnet test --nologo --filter $filter 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } finally { Pop-Location }
+                    Push-Location $repo; try { $log = (dotnet test --nologo --filter $filter 2>&1 | Out-String); $rc = $LASTEXITCODE; $ok = ($rc -eq 0) } finally { Pop-Location }
                 }
             } else {
                 $cmd = 'dotnet test --nologo'; $ran = $true
-                Push-Location $repo; try { $log = (dotnet test --nologo 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } finally { Pop-Location }
+                Push-Location $repo; try { $log = (dotnet test --nologo 2>&1 | Out-String); $rc = $LASTEXITCODE; $ok = ($rc -eq 0) } finally { Pop-Location }
             }
         } else { $ok = $false }
     } elseif ((Test-Path (Join-Path $repo 'package.json')) -and (Get-Command npm -ErrorAction SilentlyContinue)) {
         $tool = 'npm'; $cmd = 'npm test'; $ran = $true
-        Push-Location $repo; try { $log = (npm test 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } finally { Pop-Location }
+        Push-Location $repo; try { $log = (npm test 2>&1 | Out-String); $rc = $LASTEXITCODE; $ok = ($rc -eq 0) } finally { Pop-Location }
     }
 
     # matched = at least one test was actually selected + run. Read from the LOG, never the
@@ -2491,7 +2553,35 @@ function Invoke-TestRun {
     if ($scoped) { $fenceGreen = ($ok -and $matched) } else { $fenceGreen = $ok }
 
     $tail = if ($log.Length -gt 1400) { $log.Substring($log.Length - 1400) } else { $log }
-    Write-Json ([ordered]@{ ok = $ok; tool = $tool; ran = $ran; scope = $scope; slices = ($slices -join ' '); scoped = $scoped; matched = $matched; fence_green = $fenceGreen; cmd = $cmd; log_tail = $tail })
+    # The lines that NAME the failure, which a positional tail does not reliably contain:
+    # a .NET run opens with its restore banner and a runner closes with a summary, so the
+    # last 1400 characters can be entirely green while the failure sits above them.
+    $excerpt = ''; $noSetup = $false; $setupReason = ''
+    if (-not $fenceGreen) {
+        $py = Get-Py
+        if ($py) {
+            $helper = Join-Path $PSScriptRoot '..' 'python' 'aw-testlog.py'
+            if (Test-Path $helper) {
+                $label = $tool; if ($cmd) { $label = "$tool · $cmd" }
+                $label = ($label -replace '\s+', ' ')
+                if ($label.Length -gt 80) { $label = $label.Substring(0, 80) }
+                $tmp = [System.IO.Path]::GetTempFileName()
+                try {
+                    Set-Content -LiteralPath $tmp -Value $log -NoNewline -Encoding utf8
+                    $line = (& $py $helper '--file' $tmp '--label' $label '--exit' "$rc" | Select-Object -First 1)
+                    if ($line) {
+                        $h = $line | ConvertFrom-Json
+                        $excerpt = [string]$h.excerpt
+                        # "The command never ran" — no test script, no runner, no test
+                        # project. Not a red suite; the callers gate on it.
+                        $setupReason = [string]$h.reason
+                        $noSetup = [bool]$h.no_setup
+                    }
+                } catch { $excerpt = '' } finally { Remove-Item -LiteralPath $tmp -ErrorAction SilentlyContinue }
+            }
+        }
+    }
+    Write-Json ([ordered]@{ ok = $ok; tool = $tool; ran = $ran; scope = $scope; slices = ($slices -join ' '); scoped = $scoped; matched = $matched; fence_green = $fenceGreen; cmd = $cmd; log_tail = $tail; failing_excerpt = $excerpt; failing_lanes = @(); no_setup = $noSetup; setup_reason = $setupReason; setup_missing = @() })
 }
 
 function Invoke-RunMigrate {
@@ -2645,16 +2735,33 @@ function Get-CrIdToken {
 }
 
 # One change's wave, read from the documents that carry it: the delta-spec first, then the
-# model delta. Both are stamped together, so either answers; 1 is the floor for a change
-# opened before waves existed. Twin of bash _wave_of.
-function Get-WaveOf {
+# model delta. Both are stamped together, so either answers. EMPTY when neither carries a
+# readable one — `**Wave**: [N]` is the unfilled template line, so "no wave" is a state that
+# happens, and a caller who WRITES the answer somewhere must not write a number nobody
+# derived. A phantom wave is worse than none: the merge and recall fences can see that a
+# wave is missing and say so, but a 1 invented downstream reads to them as fact.
+# Twin of bash _wave_of_readable.
+function Get-WaveOfReadable {
     param([string]$FeatureDir, [string]$CrId, [string]$Repo)
     $ctx = Get-ContextDirForFeature -FeatureDir $FeatureDir -Repo $Repo
     foreach ($f in @((Join-Path $FeatureDir "changes/$CrId/delta-spec.md"), (Join-Path $ctx "domain-model.$CrId.delta.md"))) {
         if (-not (Test-Path $f)) { continue }
         $t = Get-Content $f -Raw -ErrorAction SilentlyContinue
-        if ($t -match '(?m)^\*\*Wave\*\*:\s*(\d+)') { return "$([int]$Matches[1])" }
+        if ($t -match '(?m)^\*\*Wave\*\*:\s*(\d+)') {
+            $w = [int]$Matches[1]
+            if ($w -ge 1) { return "$w" }
+        }
     }
+    return ''
+}
+
+# The same reading with the floor applied, for the readers that must show a number — a
+# listing has a column to fill and 1 is the floor for a change opened before waves existed.
+# Twin of bash _wave_of.
+function Get-WaveOf {
+    param([string]$FeatureDir, [string]$CrId, [string]$Repo)
+    $w = Get-WaveOfReadable -FeatureDir $FeatureDir -CrId $CrId -Repo $Repo
+    if ($w) { return $w }
     return '1'
 }
 
@@ -2960,26 +3067,41 @@ function Invoke-CrPaths {
 
 # ─────────────────────────── cr-overlap ────────────────────────────────────
 # Which OTHER open changes touch the same aggregates as this one — read off the
-# `## Aggregate: <Name>` headers of the pending model deltas, which is the merge unit
-# domain-model.md is organised by. Deterministic on purpose: two deltas collide when they
-# change the same aggregate, and that is a fact about two files' headings, so a regex
-# answers it exactly and the same way every run. Early warning, not enforcement — an
+# `**Aggregates touched**:` header of each pending model delta. That header names the
+# `## Aggregate: <Name>` sections of domain-model.md the delta merges into; the delta itself
+# carries no such headings, the master does. Deterministic on purpose: two deltas collide
+# when they change the same aggregate, and that is a fact about two files' headers, so a
+# regex answers it exactly and the same way every run. Early warning, not enforcement — an
 # overlap is ordinary, and what matters is that the second change is PLANNED knowing about
 # the first. The relation follows the wave: a LOWER wave is a predecessor (a dependency to
 # declare), the SAME wave a sibling (a conflict to design around), a HIGHER wave a
 # successor (it plans on top of this change — information, not an obligation). Twin of
 # bash cmd_cr_overlap.
 #
-# The aggregate names one model delta declares, in the order it declares them. A
-# placeholder heading left by the template names no aggregate, so an unfilled model delta
-# reports none rather than colliding with every other change on "<Name>".
+# The aggregate names one model delta declares, in the order its `**Aggregates touched**:`
+# header lists them — the same list finalize-delta opens master sections for. Backticked
+# names are the template's form and win when present, so prose around them adds nothing; a
+# value with no backticks is split on , ; / & "and" and each piece's leading name is taken.
+# The template placeholder (`[Root]`) and "None — behaviour only" name no aggregate, so an
+# unfilled or model-free delta reports none rather than colliding with every other change.
 function Get-DeltaAggregates {
     param([string]$Text)
     $out = @()
     if (-not $Text) { return $out }
-    foreach ($m in [regex]::Matches($Text, '(?m)^##\s*Aggregate:\s*(.+?)\s*$')) {
-        $name = $m.Groups[1].Value.Trim().Trim('`')
-        if (-not $name -or $name.StartsWith('<') -or $name.StartsWith('[')) { continue }
+    $m = [regex]::Match($Text, '(?m)^[ \t]*(?:[-*][ \t]+)?\*\*Aggregates touched(?:\*\*:|:\*\*)[ \t]*(.*)$')
+    if (-not $m.Success) { return $out }
+    $value = ([regex]::Replace($m.Groups[1].Value, '<!--.*?(?:-->|$)', '')).Trim()
+    $names = @([regex]::Matches($value, '`([^`]+)`') | ForEach-Object { $_.Groups[1].Value })
+    if ($names.Count -eq 0) {
+        $names = @(foreach ($piece in [regex]::Split($value, '[,;/&]|\band\b')) {
+            $pm = [regex]::Match($piece.Trim(), '^[A-Za-z][A-Za-z0-9_]*')
+            if ($pm.Success) { $pm.Value }
+        })
+    }
+    foreach ($name in $names) {
+        $name = $name.Trim()
+        if (-not $name -or $name.StartsWith('<') -or $name.StartsWith('[') -or
+            [regex]::IsMatch($name, '^none\b', 'IgnoreCase')) { continue }
         if ($out -notcontains $name) { $out += $name }
     }
     return $out
@@ -3106,6 +3228,344 @@ function Invoke-CrWave {
     Write-Json ([ordered]@{ cr_id = $crId; wave = [int]$wave; stamped = $stamped; delta_spec = $dspec; delta_model = $dmodel })
 }
 
+$PyCrWaveDerive = @'
+import glob, json, os, re
+
+cr = os.environ["AW_CR"]
+fd = os.environ["AW_FD"]
+ctx = os.environ["AW_CTX"]
+stamp = os.environ.get("AW_STAMP", "") == "true"
+
+CR_RX = re.compile(r"CR-\d{8}-\d{6}-[0-9A-Za-z]+")
+WAVE_RX = re.compile(r"^\*\*Wave\*\*:\s*(\d+)", re.M)
+
+
+def read(path):
+    try:
+        return open(path, encoding="utf-8").read()
+    except Exception:
+        return ""
+
+
+def wave_of(cr_id):
+    """A change states its wave in the header of its own delta documents."""
+    for p in (os.path.join(ctx, "domain-model.%s.delta.md" % cr_id),
+              os.path.join(fd, "changes", cr_id, "delta-spec.md")):
+        m = WAVE_RX.search(read(p))
+        if m:
+            return int(m.group(1))
+    for p in glob.glob(os.path.join(glob.escape(os.path.join(fd, "changes", cr_id)), "delta-*.md")):
+        m = WAVE_RX.search(read(p))
+        if m:
+            return int(m.group(1))
+    return None
+
+
+def depends_ids(text):
+    """The CR ids named under `## Depends on`, up to the next heading of that level."""
+    m = re.search(r"^##\s+Depends on\s*$(.*?)(?=^##\s|\Z)", text, re.M | re.S)
+    if not m:
+        return []
+    body = re.sub(r"<!--.*?-->", " ", m.group(1), flags=re.S)
+    return [i for i in CR_RX.findall(body) if i != cr]
+
+
+change_dir = os.path.join(fd, "changes", cr)
+docs = [os.path.join(ctx, "domain-model.%s.delta.md" % cr),
+        os.path.join(change_dir, "delta-spec.md")]
+docs += sorted(glob.glob(os.path.join(glob.escape(change_dir), "delta-*plan*.md")))
+present = [p for p in docs if os.path.isfile(p)]
+
+deps, seen = [], set()
+for p in present:
+    for i in depends_ids(read(p)):
+        if i not in seen:
+            seen.add(i)
+            deps.append(i)
+
+known, unknown = [], []
+for d in deps:
+    w = wave_of(d)
+    (known if w is not None else unknown).append({"cr_id": d, "wave": w})
+required = max([d["wave"] for d in known], default=0) + 1
+current = wave_of(cr)
+ok = current is not None and current >= required
+
+# A change with NO readable wave is stamped too, not only one sitting too low. The merge
+# and recall fences refuse on an unordered change and send the operator here, so the one
+# command they are given has to be able to write the first wave as well as correct a wrong
+# one — a remedy that declines the case it was named for is no remedy.
+stamped = []
+if stamp and (current is None or current < required):
+    line = "**Wave**: %d" % required
+    pat = re.compile(r"^\*\*Wave\*\*:.*$", re.M)
+    for p in present:
+        text = read(p)
+        if pat.search(text):
+            open(p, "w", encoding="utf-8").write(pat.sub(lambda _m: line, text, count=1))
+            stamped.append(os.path.basename(p))
+    if stamped:
+        current, ok = required, True
+
+if stamped and deps:
+    msg = "%s depends on %s, so it was raised to wave %d in %s" % (
+        cr, ", ".join("%s (wave %s)" % (d["cr_id"], d["wave"]) for d in known),
+        required, ", ".join(stamped))
+elif stamped:
+    msg = "%s declares no predecessor, so it was stamped at wave %d — the floor — in %s" % (
+        cr, required, ", ".join(stamped))
+elif not deps:
+    msg = "%s declares no predecessor, so wave %d is the floor; it carries %s" % (
+        cr, required, current if current is not None else "no wave")
+elif ok:
+    msg = "%s is at wave %s, at or above the %d its `## Depends on` requires" % (
+        cr, current, required)
+else:
+    msg = ("%s is at wave %s but depends on %s, so it must sit at wave %d — a predecessor "
+           "at the same or a higher wave is not ordered behind it at all" % (
+               cr, current, ", ".join("%s (wave %s)" % (d["cr_id"], d["wave"]) for d in known),
+               required))
+if unknown:
+    msg += ". Named but not found open: %s" % ", ".join(u["cr_id"] for u in unknown)
+
+print(json.dumps({
+    "cr_id": cr, "wave": current, "required_wave": required, "ok": ok,
+    "depends_on": known, "unknown": unknown, "depends_count": len(deps),
+    "stamped": stamped, "documents": [os.path.basename(p) for p in present],
+    "message": msg,
+}))
+'@
+
+# THE WAVE A CHANGE'S OWN DOCUMENTS IMPLY, from their `## Depends on` sections. Twin of the
+# bash cmd_cr_wave_derive, running the SAME python payload — see the bash comment for why
+# the declaration, not cr-setup's default, is the ordering authority.
+function Invoke-CrWaveDerive {
+    param([string[]]$Rest)
+    $crId = ''; $fdArg = ''; $stamp = $false
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--cr-id','-CrId' } { $crId = $Rest[++$i] }
+            { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] }
+            { $_ -in '--stamp','-Stamp' } { $stamp = $true }
+        }
+    }
+    $crId = Get-CrIdToken -Raw $crId
+    if (-not $crId) { Write-Error 'cr-wave-derive: --cr-id is required'; exit 1 }
+    $py = Get-Py
+    if (-not $py) { Write-Error 'cr-wave-derive: python3 is required'; exit 1 }
+    $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'cr-wave-derive: no feature set and no --feature-dir'; exit 1 }
+    $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
+    $env:AW_CR = $crId; $env:AW_FD = $fd; $env:AW_CTX = $ctx
+    $env:AW_STAMP = $(if ($stamp) { 'true' } else { 'false' })
+    try { $PyCrWaveDerive | & $py - } finally {
+        Remove-Item Env:AW_CR, Env:AW_FD, Env:AW_CTX, Env:AW_STAMP -ErrorAction SilentlyContinue
+    }
+}
+
+$PyCrRebase = @'
+import glob, json, os, re
+
+cr = os.environ["AW_CR"]
+fd = os.environ["AW_FD"]
+ctx = os.environ["AW_CTX"]
+stamp = os.environ.get("AW_STAMP", "") == "true"
+
+CR_RX = re.compile(r"CR-\d{8}-\d{6}-[0-9A-Za-z]+")
+TICK_RX = re.compile(r"`([^`]+)`")
+
+
+def read(path):
+    try:
+        return open(path, encoding="utf-8").read()
+    except Exception:
+        return ""
+
+
+def header(text, name):
+    m = re.search(r"^\*\*%s\*\*:[ \t]*(.+?)[ \t]*(?:<!--.*)?$" % re.escape(name), text, re.M)
+    if not m:
+        return ""
+    v = m.group(1).strip()
+    return "" if (v.startswith("[") and v.endswith("]")) else v
+
+
+def norm(v):
+    v = (v or "").strip()
+    return "" if not v else (v if v.startswith("v") else "v" + v)
+
+
+def as_tuple(v):
+    parts = re.findall(r"\d+", v or "")
+    return tuple(int(p) for p in parts) if parts else None
+
+
+def aggregates(text):
+    """The `**Aggregates touched**:` header — the list finalize-delta opens sections for."""
+    m = re.search(r"^[ \t]*(?:[-*][ \t]+)?\*\*Aggregates touched(?:\*\*:|:\*\*)[ \t]*(.*)$", text, re.M)
+    if not m:
+        return set()
+    value = re.sub(r"<!--.*?(?:-->|$)", "", m.group(1)).strip()
+    names = TICK_RX.findall(value)
+    if not names:
+        names = [p.strip() for p in re.split(r"[,;/&]|\band\b", value) if p.strip()]
+        names = [re.match(r"[A-Za-z_][A-Za-z0-9_]*", n).group(0)
+                 for n in names if re.match(r"[A-Za-z_][A-Za-z0-9_]*", n)]
+    return {n for n in names if not n.startswith(("<", "[")) and not re.match(r"(?i)none\b", n)}
+
+
+def landed_since(text, base):
+    """CR ids in Change History rows whose version is ABOVE `base` — what moved the master
+    since this delta was stamped. A row with no readable version counts, because a row this
+    cannot place is one it cannot prove is older."""
+    ids, base_t = [], as_tuple(base)
+    for line in text.split("\n"):
+        if not line.strip().startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) < 2 or set("".join(cells)) <= set("-: "):
+            continue
+        row_t = as_tuple(cells[0]) if re.match(r"^v?\d", cells[0]) else None
+        if row_t is None:
+            continue
+        if base_t is not None and row_t <= base_t:
+            continue
+        for i in CR_RX.findall(line):
+            if i != cr and i not in ids:
+                ids.append(i)
+    return ids
+
+
+def model_delta_of(cr_id):
+    """A change's model half: beside the master while open, in its archive once closed."""
+    p = os.path.join(ctx, "domain-model.%s.delta.md" % cr_id)
+    if os.path.isfile(p):
+        return read(p)
+    for feat in sorted(os.listdir(ctx)) if os.path.isdir(ctx) else []:
+        a = os.path.join(ctx, feat, "changes", "archive", cr_id, "domain-model.delta.md")
+        if os.path.isfile(a):
+            return read(a)
+    return ""
+
+
+my_spec = os.path.join(fd, "changes", cr, "delta-spec.md")
+my_model = os.path.join(ctx, "domain-model.%s.delta.md" % cr)
+spec_master = os.path.join(fd, "spec.md")
+model_master = os.path.join(ctx, "domain-model.md")
+
+spec_text, model_text = read(my_spec), read(my_model)
+base_version = norm(header(spec_text, "Base version"))
+base_ctx = norm(header(model_text, "Base context version"))
+
+current = ""
+try:
+    current = norm(json.load(open(os.path.join(fd, "active_version.json"), encoding="utf-8")).get("version", ""))
+except Exception:
+    current = ""
+if not current:
+    current = norm(header(read(spec_master), "Version"))
+current_ctx = norm(header(read(model_master), "Version"))
+
+moved = bool(base_version and current and base_version != current)
+ctx_moved = bool(base_ctx and current_ctx and base_ctx != current_ctx)
+
+# WHAT LANDED IN BETWEEN, and whether any of it touched what this delta touches. A delta
+# whose aggregates nobody else moved still applies to the master it was written against;
+# one whose aggregates a landed change rewrote does not, and no stamp can make it.
+mine = aggregates(model_text)
+intervening = landed_since(read(spec_master), base_version) if moved else []
+if ctx_moved:
+    for i in landed_since(read(model_master), base_ctx):
+        if i not in intervening:
+            intervening.append(i)
+
+rows, conflicts = [], []
+for i in intervening:
+    theirs = aggregates(model_delta_of(i))
+    shared = sorted(mine & theirs) if (mine and theirs) else []
+    # Unknown aggregates fail CLOSED: a change this cannot read is one it cannot clear.
+    unknown = not theirs
+    rows.append({"cr_id": i, "aggregates": sorted(theirs), "shared": shared, "unknown": unknown})
+    if shared or unknown:
+        conflicts.append({"cr_id": i, "shared": shared, "unknown": unknown})
+
+clean = (moved or ctx_moved) and not conflicts
+stamped = []
+if stamp and clean:
+    if moved and os.path.isfile(my_spec):
+        open(my_spec, "w", encoding="utf-8").write(
+            re.sub(r"^\*\*Base version\*\*:.*$", "**Base version**: %s" % current,
+                   spec_text, count=1, flags=re.M))
+        stamped.append({"file": os.path.basename(my_spec), "header": "Base version",
+                        "from": base_version, "to": current})
+    if ctx_moved and os.path.isfile(my_model):
+        open(my_model, "w", encoding="utf-8").write(
+            re.sub(r"^\*\*Base context version\*\*:.*$", "**Base context version**: %s" % current_ctx,
+                   model_text, count=1, flags=re.M))
+        stamped.append({"file": os.path.basename(my_model), "header": "Base context version",
+                        "from": base_ctx, "to": current_ctx})
+    if stamped:
+        moved = ctx_moved = False
+
+ok = not (moved or ctx_moved)
+if not (base_version or base_ctx):
+    msg = "%s carries no base stamp, so there is nothing to compare — treated as not moved" % cr
+elif ok and not stamped:
+    msg = "%s is stamped against the current masters (%s, context %s)" % (cr, current or "—", current_ctx or "—")
+elif stamped:
+    msg = "%s was re-stamped: %s. Nothing that landed in between (%s) touched its aggregates (%s)" % (
+        cr, "; ".join("%s %s → %s" % (s["header"], s["from"], s["to"]) for s in stamped),
+        ", ".join(r["cr_id"] for r in rows) or "no recorded change", ", ".join(sorted(mine)) or "none named")
+else:
+    parts = []
+    for c in conflicts:
+        parts.append("%s (%s)" % (c["cr_id"], "aggregates unreadable" if c["unknown"]
+                                  else "also touched " + ", ".join(c["shared"])))
+    msg = ("%s was authored against %s%s but the masters are at %s%s, and what landed in "
+           "between overlaps it: %s" % (
+               cr, base_version or "—", "" if not base_ctx else " (context %s)" % base_ctx,
+               current or "—", "" if not current_ctx else " (context %s)" % current_ctx,
+               "; ".join(parts)))
+
+print(json.dumps({
+    "cr_id": cr, "ok": ok, "clean": clean, "moved": moved, "context_moved": ctx_moved,
+    "base_version": base_version, "current_version": current,
+    "base_context_version": base_ctx, "current_context_version": current_ctx,
+    "aggregates": sorted(mine), "landed_since": rows,
+    "conflicts": conflicts, "conflict_count": len(conflicts),
+    "conflict_ids": ", ".join(c["cr_id"] for c in conflicts),
+    "stamped": stamped, "message": msg,
+}))
+'@
+
+
+# RE-STAMP a change's base versions when nothing that landed in between touched its
+# aggregates. Twin of the bash cmd_cr_rebase, running the SAME python payload — see the
+# bash comment for what "applies cleanly" means and why an unreadable delta fails closed.
+function Invoke-CrRebase {
+    param([string[]]$Rest)
+    $crId = ''; $fdArg = ''; $stamp = $false
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--cr-id','-CrId' } { $crId = $Rest[++$i] }
+            { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] }
+            { $_ -in '--stamp','-Stamp' } { $stamp = $true }
+        }
+    }
+    $crId = Get-CrIdToken -Raw $crId
+    if (-not $crId) { Write-Error 'cr-rebase: --cr-id is required'; exit 1 }
+    $py = Get-Py
+    if (-not $py) { Write-Error 'cr-rebase: python3 is required'; exit 1 }
+    $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'cr-rebase: no feature set and no --feature-dir'; exit 1 }
+    $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
+    $env:AW_CR = $crId; $env:AW_FD = $fd; $env:AW_CTX = $ctx
+    $env:AW_STAMP = $(if ($stamp) { 'true' } else { 'false' })
+    try { $PyCrRebase | & $py - } finally {
+        Remove-Item Env:AW_CR, Env:AW_FD, Env:AW_CTX, Env:AW_STAMP -ErrorAction SilentlyContinue
+    }
+}
+
 function Invoke-CrSetup {
     param([string[]]$Rest)
     $crId = ''; $fdArg = ''; $title = ''; $force = ''; $wave = ''
@@ -3502,13 +3962,6 @@ function Invoke-CrMergeCheck {
     if (-not $fd) { Write-Error 'cr-merge-check: no feature set and no --feature-dir'; exit 1 }
     $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
 
-    function Get-WaveFile([string]$path) {
-        if (Test-Path -LiteralPath $path) {
-            $m = [regex]::Match((Get-Content -LiteralPath $path -Raw), '(?m)^\*\*Wave\*\*:[ \t]*(\d+)')
-            if ($m.Success) { return [int]$m.Groups[1].Value }
-        }
-        return 1
-    }
     function Format-Ver([string]$v) {
         $v = "$v".Trim()
         if (-not $v) { return '' }
@@ -3516,7 +3969,6 @@ function Invoke-CrMergeCheck {
     }
 
     $mySpec = Join-Path $fd "changes/$crId/delta-spec.md"
-    $wave = Get-WaveFile $mySpec
     $baseVersion = Format-Ver (Get-MdHeader -Path $mySpec -Name 'Base version')
 
     # The master's CURRENT version, from the ledger — the same authority version-read
@@ -3532,51 +3984,59 @@ function Invoke-CrMergeCheck {
     # is absence of evidence and is not treated as a move.
     $rebaseNeeded = [bool]($baseVersion -and $current -and ($baseVersion -ne $current))
 
-    # EVERY open change in the context, both halves. changes/<id>/ under each feature is the
-    # authority for "open"; the pending model deltas are unioned in so a model-only artifact
-    # of a half-built change is still seen.
-    $opens = [ordered]@{}
-    if (Test-Path -LiteralPath $ctx) {
-        foreach ($feat in (Get-ChildItem -LiteralPath $ctx -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
-            $ch = Join-Path $feat.FullName 'changes'
-            if (-not (Test-Path -LiteralPath $ch)) { continue }
-            foreach ($d in (Get-ChildItem -LiteralPath $ch -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
-                if ($d.Name -eq 'archive') { continue }
-                if (-not $opens.Contains($d.Name)) {
-                    $opens[$d.Name] = [ordered]@{ cr_id = $d.Name
-                                                  wave = (Get-WaveFile (Join-Path $d.FullName 'delta-spec.md'))
-                                                  feature = $feat.Name }
-                }
-            }
-        }
-        foreach ($f in (Get-ChildItem -LiteralPath $ctx -File -ErrorAction SilentlyContinue | Sort-Object Name)) {
-            $m = [regex]::Match($f.Name, '^domain-model\.(.+)\.delta\.md$')
-            if (-not $m.Success) { continue }
-            $other = $m.Groups[1].Value
-            if (-not $opens.Contains($other)) {
-                $opens[$other] = [ordered]@{ cr_id = $other; wave = (Get-WaveFile $f.FullName); feature = '' }
+    # BOTH CONTEXT-WIDE QUESTIONS COME FROM aw-crstate, the same module the bash payload
+    # loads, so the two shells cannot answer them differently — which they did while each
+    # carried its own copy of the scan.
+    #
+    # PREDECESSORS. Every open change in the context, both halves: changes/<id>/ under each
+    # feature is the authority for "open", and the pending model deltas are unioned in so a
+    # model-only artifact of a half-built change is still seen. A change whose `**Wave**:`
+    # is unreadable is reported as unordered rather than assumed to be wave 1.
+    #
+    # MERGED-OPEN. The masters can move without the version moving: finalize-delta merges
+    # and close-delta bumps, so between the two spec.md carries a change the number does not
+    # yet reflect, and a second delta sharing the same base_version would compare equal and
+    # merge onto masters that had already shifted under it. A change is MERGED when its id
+    # is the CR cell of a Change History row — in this feature's spec or in the context
+    # model every feature shares, so a SIBLING feature's merged-unclosed change is no longer
+    # invisible. A sibling blocks only where it touched an aggregate this delta also names.
+    #
+    # Fails CLOSED: an unreadable helper reports blocking and nothing ordered.
+    $py = Get-Py
+    $crstate = Join-Path $PSScriptRoot '..' 'python' 'aw-crstate.py'
+    # `answered` is what says the reader ran, not the shape of what it returned: NO blocking
+    # merged-open change is an empty array, which is exactly what a failed read looks like.
+    $order = $null; $mergedOpen = @(); $mergedText = ''; $answered = $false
+    $why = 'python or aw-crstate.py not found'
+    if ($py -and (Test-Path $crstate)) {
+        try {
+            $line = (& $py $crstate 'wave-order' '--cr' $crId '--feature-dir' $fd '--context-dir' $ctx '--direction' 'lower' '--scope' 'context' | Select-Object -First 1)
+            if ($line) { $order = ($line | ConvertFrom-Json) }
+            $line = (& $py $crstate 'merged-open' '--cr' $crId '--feature-dir' $fd '--context-dir' $ctx | Select-Object -First 1)
+            if ($line) {
+                $parsed = ($line | ConvertFrom-Json)
+                $mergedOpen = @($parsed.blocking); $mergedText = "$($parsed.blocking_text)"; $answered = $true
             }
+        } catch {
+            $order = $null; $answered = $false; $why = "$_"
         }
     }
-    $blockers = @(foreach ($k in ($opens.Keys | Sort-Object)) {
-        if ($k -ne $crId -and $opens[$k].wave -lt $wave) { $opens[$k] }
-    })
-
-    # THE MASTERS CAN MOVE WITHOUT THE VERSION MOVING. finalize-delta merges and close-delta
-    # bumps, so between the two spec.md carries a change the number does not yet reflect —
-    # and a second delta sharing the same base_version would compare equal and merge onto
-    # masters that had already shifted under it. An id appearing in spec.md is the on-disk
-    # proof that the merge ran (the Change History row finalize-delta appends), the same
-    # evidence cr-recall-check reads for the same question.
-    $specText = ''
-    $specPath = Join-Path $fd 'spec.md'
-    if (Test-Path -LiteralPath $specPath) { $specText = (Get-Content -LiteralPath $specPath -Raw) }
-    $mergedOpen = @(foreach ($k in ($opens.Keys | Sort-Object)) {
-        if ($k -ne $crId -and $specText.Contains($k)) { $opens[$k] }
-    })
+    if (-not $order) {
+        $order = [pscustomobject]@{ wave = $null; wave_known = $false; related = @(); related_count = 0
+                                    related_ids = ''; unknown = @(); unknown_count = 0; unknown_ids = ''
+                                    unknown_blocks = $true; wave_ordering_ok = $false
+                                    wave_problem = "the wave reader could not be run ($why), so no open change in this context is ordered against $crId at all" }
+    }
+    if (-not $answered) {
+        $mergedOpen = @([pscustomobject]@{ cr_id = "(merged-open check failed: $why)"; blocking = $true })
+        $mergedText = $mergedOpen[0].cr_id
+    }
+    $blockers = @($order.related)
 
     Write-Json ([ordered]@{
-        ok = $true; cr_id = $crId; wave = $wave
+        ok = $true; cr_id = $crId
+        wave = $(if ($null -ne $order.wave) { $order.wave } else { '' })
+        wave_known = [bool]$order.wave_known
         exists = (Test-Path -LiteralPath (Join-Path $fd "changes/$crId"))
         # REBASE half — the masters moved because a change CLOSED and bumped the number.
         base_version = $baseVersion; current_version = $current
@@ -3584,14 +4044,19 @@ function Invoke-CrMergeCheck {
         base_stamped = [bool]$baseVersion
         blockers = @($blockers); blocker_count = @($blockers).Count
         has_blockers = (@($blockers).Count -gt 0)
-        blocker_ids = (@($blockers | ForEach-Object { '{0} (wave {1})' -f $_.cr_id, $_.wave }) -join ', ')
+        blocker_ids = $order.related_ids
+        # The changes this one cannot be ordered against at all, in either direction.
+        unordered = @($order.unknown); unordered_count = $order.unknown_count
+        unordered_ids = $order.unknown_ids
+        wave_ordering_ok = [bool]$order.wave_ordering_ok
+        wave_problem = $order.wave_problem
         # The other way the masters move: a change MERGED and has not closed yet.
         merged_open = @($mergedOpen); merged_open_count = @($mergedOpen).Count
         has_merged_open = (@($mergedOpen).Count -gt 0)
-        merged_open_ids = (@($mergedOpen | ForEach-Object { $_.cr_id }) -join ', ')
-        # All three refusals as ONE positive flag, because the engine takes no compound
-        # condition and a gate reading three booleans would need three passes over one question.
-        merge_ok = ((-not $rebaseNeeded) -and (@($blockers).Count -eq 0) -and (@($mergedOpen).Count -eq 0))
+        merged_open_ids = $mergedText
+        # All four refusals as ONE positive flag, because the engine takes no compound
+        # condition and a gate reading four booleans would need four passes over one question.
+        merge_ok = ((-not $rebaseNeeded) -and [bool]$order.wave_ordering_ok -and (@($blockers).Count -eq 0) -and (@($mergedOpen).Count -eq 0))
     })
 }
 
@@ -3607,47 +4072,62 @@ function Invoke-CrRecallCheck {
     $crId = Get-CrIdToken -Raw $crId
     if (-not $crId) { Write-Error 'cr-recall-check: --cr-id required'; exit 1 }
     $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
     if (-not $fd) { Write-Error 'cr-recall-check: no feature set and no --feature-dir'; exit 1 }
     $changes = Join-Path $fd 'changes'
     $crDir   = Join-Path $changes $crId
 
-    function Get-WaveOf([string]$dir) {
-        $p = Join-Path $dir 'delta-spec.md'
-        if (Test-Path $p) {
-            $m = [regex]::Match((Get-Content $p -Raw), '(?m)^\*\*Wave\*\*:[ \t]*(\d+)')
-            if ($m.Success) { return [int]$m.Groups[1].Value }
-        }
-        return 1
-    }
-
+    # MERGED = a Change History row whose CR cell IS this change, in this feature's spec or
+    # in the shared context model — aw-crstate owns that test for all three readers of it.
+    # Fails CLOSED: an unreadable helper reports merged, never "never merged", which is the
+    # answer that would let close-delta archive a change nobody merged.
+    #
+    # DEPENDANTS come from the same module the merge fence reads in the opposite direction.
+    # An unreadable `**Wave**:` is not wave 1 here either: it used to mean the change was
+    # not counted as higher, so recall withdrew the ground from under a dependant it could
+    # not see. Waves have no ceiling, so any unordered change could sit above this one.
     $spec = Join-Path $fd 'spec.md'
-    $merged = $false; $evidence = ''
-    if (Test-Path $spec) {
-        foreach ($line in (Get-Content $spec)) {
-            if ("$line".Contains($crId)) { $merged = $true; $evidence = "$line".Trim(); break }
-        }
+    $merged = $true; $evidence = '(merged check unavailable — treated as merged)'
+    $py = Get-Py
+    $crstate = Join-Path $PSScriptRoot '..' 'python' 'aw-crstate.py'
+    $order = $null; $why = 'python or aw-crstate.py not found'
+    if ($py -and (Test-Path $crstate)) {
+        try {
+            $line = (& $py $crstate 'merged' '--cr' $crId '--doc' $spec '--doc' (Join-Path $ctx 'domain-model.md') | Select-Object -First 1)
+            if ($line) {
+                $h = $line | ConvertFrom-Json
+                $merged = [bool]$h.merged; $evidence = [string]$h.evidence
+            }
+            $line = (& $py $crstate 'wave-order' '--cr' $crId '--feature-dir' $fd '--context-dir' $ctx '--direction' 'higher' '--scope' 'feature' | Select-Object -First 1)
+            if ($line) { $order = ($line | ConvertFrom-Json) }
+        } catch { $order = $null; $why = "$_" }
     }
-
-    $wave = if (Test-Path $crDir) { Get-WaveOf $crDir } else { 1 }
-    $dependants = @()
-    if (Test-Path $changes) {
-        foreach ($d in (Get-ChildItem -LiteralPath $changes -Directory | Sort-Object Name)) {
-            if ($d.Name -eq $crId -or $d.Name -eq 'archive') { continue }
-            $w = Get-WaveOf $d.FullName
-            if ($w -gt $wave) { $dependants += [ordered]@{ cr_id = $d.Name; wave = $w } }
-        }
+    if (-not $order) {
+        $order = [pscustomobject]@{ wave = $null; wave_known = $false; related = @(); related_count = 0
+                                    related_ids = ''; unknown = @(); unknown_count = 0; unknown_ids = ''
+                                    unknown_blocks = $true; wave_ordering_ok = $false
+                                    wave_problem = "the wave reader could not be run ($why), so no open change in this feature is ordered against $crId at all" }
     }
+    $dependants = @($order.related)
+
     Write-Json ([ordered]@{
-        ok              = $true
-        cr_id           = $crId
-        exists          = (Test-Path $crDir)
-        wave            = $wave
-        merged          = $merged
-        merge_evidence  = $evidence
-        dependants      = @($dependants)
-        dependant_ids   = (@($dependants | ForEach-Object { '{0} (wave {1})' -f $_.cr_id, $_.wave }) -join ', ')
-        dependant_count = @($dependants).Count
-        has_dependants  = (@($dependants).Count -gt 0)
+        ok               = $true
+        cr_id            = $crId
+        exists           = (Test-Path $crDir)
+        wave             = $(if ($null -ne $order.wave) { $order.wave } else { '' })
+        wave_known       = [bool]$order.wave_known
+        merged           = $merged
+        merge_evidence   = $evidence
+        dependants       = @($dependants)
+        dependant_ids    = $order.related_ids
+        dependant_count  = @($dependants).Count
+        has_dependants   = (@($dependants).Count -gt 0)
+        # The changes this one cannot be ordered against at all, in either direction.
+        unordered        = @($order.unknown)
+        unordered_count  = $order.unknown_count
+        unordered_ids    = $order.unknown_ids
+        wave_ordering_ok = [bool]$order.wave_ordering_ok
+        wave_problem     = $order.wave_problem
     })
 }
 
@@ -3669,14 +4149,65 @@ function Invoke-CrRecallCheck {
 # WHY THE GATE AND NOT THE AUTHOR. Stamping at `plan` would record "this plan was authored
 # from that spec". The question implement depends on is stronger — "were these plans PROVEN
 # against this spec" — and a plan authored from the current spec can still be wrong. So the
-# receipt is written where the proof happens, by analyze-plan, on green, and it hashes every
-# document the gate actually read: the spec, the context's domain model (check 4 reads it)
-# and each lane plan that was present.
+# receipt is written where the proof happens, by analyze-plan, and it hashes every document
+# the gate actually read: the spec, the context's domain model (check 4 reads it) and each
+# lane plan that was present.
+#
+# THE RECEIPT CARRIES THE VERDICT, and every master-mode run writes one. A receipt written
+# only on a clean pass is never written on a feature whose spec misses a domain constraint —
+# a LIFT-FAILURE analyze-plan may not close — and then the staleness check has nothing to
+# compare. The verdict splits the gaps by who can close them (plan-gaps):
+#   conformant   no gaps
+#   routed-gaps  only gaps /appweaver specify must close — implement warns and generates
+#   gaps         at least one gap a plan rewrite closes — implement refuses
 #
 # The absence of a receipt is INFORMATION, not an error: it means this feature has never
 # been through the gate, which every tree that predates this op is true of. It is reported
-# as untracked and blocks nothing. Only a receipt that EXISTS and no longer matches is a
-# refusal, because that tree has been gated once and the bytes have moved since.
+# as untracked and blocks nothing. A receipt that EXISTS refuses when the bytes have moved
+# since, or when its verdict is `gaps`. A receipt written before the verdict existed was
+# written on a clean pass, and reads as `conformant`. Twins of the bash ops.
+
+# Which analyze-plan gaps a plan rewrite can close, and which only /appweaver specify can.
+# A gap routes to specify when the analyze pass tagged it `route: specify` (a constraint the
+# spec never lifted, structure domain-model.md does not define, behaviour the spec does not
+# describe), or when its text opens with LIFT-FAILURE whatever the tag says. Anything else —
+# an untagged gap included — is a plan gap. Unreadable input is one plan gap: a verdict that
+# could not be read must not pass.
+function Invoke-PlanGaps {
+    param([string[]]$Rest)
+    $raw = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) { { $_ -in '--gaps','-Gaps' } { $raw = $Rest[++$i] } }
+    }
+    $gaps = @(); $readable = $true
+    if ("$raw".Trim()) {
+        try {
+            $parsed = ConvertFrom-Json -InputObject $raw -NoEnumerate -ErrorAction Stop
+            if ($parsed -is [array]) { $gaps = @($parsed) } else { $readable = $false }
+        } catch { $readable = $false }
+    }
+    $plan = 0; $routed = @()
+    foreach ($g in $gaps) {
+        if ($g -is [System.Management.Automation.PSCustomObject]) {
+            $text = "$($g.gap)".Trim(); $route = "$($g.route)".Trim().ToLower(); $ref = "$($g.spec_ref)".Trim()
+        } else {
+            $text = "$g".Trim(); $route = ''; $ref = ''
+        }
+        if ($text.ToUpper().StartsWith('LIFT-FAILURE') -or $route -eq 'specify') {
+            $routed += $(if ($ref -and $ref -ne '—') { '{0}: {1}' -f $ref, $text } else { $text })
+        } else {
+            $plan++
+        }
+    }
+    if (-not $readable) { $plan++ }
+    $verdict = if ($plan -gt 0) { 'gaps' } elseif ($routed.Count -gt 0) { 'routed-gaps' } else { 'conformant' }
+    Write-Json ([ordered]@{
+        ok = $true; readable = $readable; verdict = $verdict; plan_ok = ($plan -eq 0)
+        plan_gaps = $plan; routed_gaps = $routed.Count; routed = @($routed)
+        routed_csv = ($routed -join '; ')
+    })
+}
+
 function Get-FileSha {
     # -LiteralPath throughout: -Path reads [ and ] as a wildcard character class, so a
     # repo living under a bracketed directory name would silently hash nothing.
@@ -3685,53 +4216,26 @@ function Get-FileSha {
     return (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLower()
 }
 
+# THE RULE ITSELF LIVES IN python/aw-plangate.py, which both shells invoke. It was a set
+# of sha comparisons written twice — a heredoc in bash, this function natively — and every
+# change to it had to be re-derived here by hand and kept in step by eye. It changed twice
+# that way. These two are now thin wrappers: resolve the feature, hand over.
 function Invoke-PlanGateStamp {
     param([string[]]$Rest)
-    $fdArg = ''; $specVersion = ''; $mode = 'master'
+    $fdArg = ''; $pass = @()
     for ($i = 0; $i -lt $Rest.Count; $i++) {
-        switch ($Rest[$i]) {
-            { $_ -in '--feature-dir','-FeatureDir' }   { $fdArg = $Rest[++$i] }
-            { $_ -in '--spec-version','-SpecVersion' } { $specVersion = $Rest[++$i] }
-            { $_ -in '--mode','-Mode' }                { $mode = $Rest[++$i] }
-        }
+        if ($Rest[$i] -in '--feature-dir','-FeatureDir') { $fdArg = $Rest[++$i] }
+        else { $pass += $Rest[$i] }
     }
     $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
     if (-not $fd) { Write-Error 'plan-gate-stamp: no feature set and no --feature-dir'; exit 1 }
     $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
-    # Every document the gate READ. A lane that is not declared has no plan on disk and is
-    # simply absent from the map — the check treats a name it does not carry as not gated,
-    # never as changed, so declaring a second lane later does not read as tampering.
-    #
-    # THE LEGACY NAMES ARE HERE FOR THE SAME REASON version-stamp CARRIES THEM. feature-paths
-    # resolves design.md / design.ui.md under the backend_plan / frontend_plan keys, so a tree
-    # that has not been through `plan` since the rename — every brownfield feature `adopt`
-    # produces — is GATED on those documents. Hashing only the new names would leave such a
-    # feature with an empty plan map: a receipt that looks tracked and fresh while the document
-    # implement actually generates from is unwatched.
-    $plans = [ordered]@{}
-    foreach ($name in @('backend-plan.md','frontend-plan.md','design.md','design.ui.md')) {
-        $h = Get-FileSha -Path (Join-Path $fd $name)
-        if ($h) { $plans[$name] = $h }
-    }
-    $rec = [ordered]@{
-        gated        = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
-        gate_mode    = $mode
-        spec_version = $specVersion.Trim()
-        spec_sha     = (Get-FileSha -Path (Join-Path $fd 'spec.md'))
-        model_sha    = (Get-FileSha -Path (Join-Path $ctx 'domain-model.md'))
-        plans        = $plans
-        note         = ('Written by analyze-plan when it PASSED. It records the bytes that were ' +
-                        'proven against each other, not a version — the plans'' **Version**: headers ' +
-                        'are stamped in lockstep by close-delta and cannot answer this. implement ' +
-                        'reads it through plan-gate-check.')
-    }
-    $p = Join-Path $fd '.aw-plan-gate.json'
-    ($rec | ConvertTo-Json -Depth 6) + "`n" | Set-Content -LiteralPath $p -NoNewline -Encoding utf8
-    Write-Json ([ordered]@{
-        file = (ConvertTo-RepoRelative -Path $p -RepoRoot $repo); gated = $rec.gated
-        spec_version = $rec.spec_version; hashed = @($plans.Keys | Sort-Object)
-        count = $plans.Count; ok = $true
-    })
+    $py = Get-Py
+    if (-not $py) { Write-Error 'plan-gate-stamp: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-plangate.py'
+    if (-not (Test-Path $core)) { Write-Error "plan-gate-stamp: core not found at $core"; exit 1 }
+    & $py $core stamp --feature-dir $fd --context-dir $ctx --root $repo @pass
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 }
 
 function Invoke-PlanGateCheck {
@@ -3743,49 +4247,38 @@ function Invoke-PlanGateCheck {
     $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
     if (-not $fd) { Write-Error 'plan-gate-check: no feature set and no --feature-dir'; exit 1 }
     $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
-    $p = Join-Path $fd '.aw-plan-gate.json'
-    $rec = $null
-    if (Test-Path -LiteralPath $p -PathType Leaf) {
-        try { $rec = Get-Content -LiteralPath $p -Raw | ConvertFrom-Json } catch { $rec = $null }
-    }
-    $out = [ordered]@{
-        file = (ConvertTo-RepoRelative -Path $p -RepoRoot $repo); tracked = [bool]$rec
-        gate_fresh = $false; spec_moved = $false; model_moved = $false
-        plans_changed = @(); plans_changed_csv = ''; gated = ''; spec_version = ''
-        reason = ''; ok = $true
-    }
-    if (-not $rec) {
-        # Never gated. Not a failure and not a stale plan — an unknown, and the only honest
-        # thing to report about a tree that has not run analyze-plan since this op existed.
-        $out.reason = 'no .aw-plan-gate.json — this feature has not passed analyze-plan since the gate began leaving a receipt'
-    } else {
-        $out.gated = [string]$rec.gated
-        $out.spec_version = [string]$rec.spec_version
-        $specSha = [string]$rec.spec_sha
-        $out.spec_moved = ($specSha -and $specSha -ne (Get-FileSha -Path (Join-Path $fd 'spec.md')))
-        # A model recorded as absent that is still absent has not moved. A context that
-        # GAINED a domain model since the gate has moved: check 4 never ran against it.
-        $out.model_moved = ([string]$rec.model_sha -ne (Get-FileSha -Path (Join-Path $ctx 'domain-model.md')))
-        $changed = @()
-        if ($rec.plans) {
-            foreach ($name in @($rec.plans.PSObject.Properties.Name | Sort-Object)) {
-                if ((Get-FileSha -Path (Join-Path $fd $name)) -ne [string]$rec.plans.$name) { $changed += $name }
-            }
-        }
-        $out.plans_changed = @($changed)
-        $out.plans_changed_csv = ($changed -join ', ')
-        $out.gate_fresh = (-not ($out.spec_moved -or $out.model_moved -or $changed.Count -gt 0))
-        if ($out.gate_fresh) {
-            $out.reason = 'the spec, the model and every gated plan are byte-identical to what analyze-plan passed on {0}' -f $out.gated
-        } else {
-            $bits = @()
-            if ($out.spec_moved)  { $bits += 'spec.md has changed' }
-            if ($out.model_moved) { $bits += 'domain-model.md has changed' }
-            if ($changed.Count -gt 0) { $bits += ('{0} changed (a re-derive by `plan main`, or a hand edit)' -f ($changed -join ', ')) }
-            $out.reason = 'since analyze-plan passed on {0}: {1}' -f $out.gated, ($bits -join '; ')
-        }
-    }
-    Write-Json $out
+    $py = Get-Py
+    if (-not $py) { Write-Error 'plan-gate-check: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-plangate.py'
+    if (-not (Test-Path $core)) { Write-Error "plan-gate-check: core not found at $core"; exit 1 }
+    & $py $core check --feature-dir $fd --context-dir $ctx --root $repo
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
+# Which of a lane plan's elements the generated code realises. One implementation
+# (python/aw-plan-coverage.py), called identically by both shells — see the bash twin.
+# Split a gate's findings by the command that closes each one. Twin of the bash
+# cmd_gap_route, calling the SAME aw-gaps.py — see the bash comment for why a plan
+# defect must never be routed to `implement`.
+function Invoke-GapRoute {
+    param([string[]]$Rest)
+    $py = Get-Py
+    if (-not $py) { Write-Error 'gap-route: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-gaps.py'
+    if (-not (Test-Path $core)) { Write-Error "gap-route: core not found at $core"; exit 1 }
+    & $py $core route @Rest
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
+function Invoke-PlanCoverage {
+    param([string[]]$Rest)
+    $py = Get-Py
+    if (-not $py) { Write-Error 'plan-coverage: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-plan-coverage.py'
+    if (-not (Test-Path $core)) { Write-Error "plan-coverage: core not found at $core"; exit 1 }
+    $repo = Get-RepoRoot
+    & $py $core '--repo' $repo @Rest
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 }
 
 # Stamp a version into the MASTER documents' `**Version**:` headers — the
@@ -3917,6 +4410,8 @@ switch ($sub) {
     'cr-overlap'       { Invoke-CrOverlap        -Rest $rest }
     'cr-activate'      { Invoke-CrActivate       -Rest $rest }
     'cr-wave'          { Invoke-CrWave           -Rest $rest }
+    'cr-wave-derive'   { Invoke-CrWaveDerive     -Rest $rest }
+    'cr-rebase'        { Invoke-CrRebase         -Rest $rest }
     'cr-archive'       { Invoke-CrArchive        -Rest $rest }
     'cr-recall-check'  { Invoke-CrRecallCheck    -Rest $rest }
     'cr-merge-check'   { Invoke-CrMergeCheck     -Rest $rest }
@@ -3925,8 +4420,11 @@ switch ($sub) {
     'context-paths'    { Invoke-ContextPaths     -Rest $rest }
     'model-scaffold'   { Invoke-ModelScaffold    -Rest $rest }
     'version-stamp'    { Invoke-VersionStamp     -Rest $rest }
+    'plan-gaps'        { Invoke-PlanGaps         -Rest $rest }
     'plan-gate-stamp'  { Invoke-PlanGateStamp    -Rest $rest }
     'plan-gate-check'  { Invoke-PlanGateCheck    -Rest $rest }
+    'plan-coverage'    { Invoke-PlanCoverage     -Rest $rest }
+    'gap-route'        { Invoke-GapRoute         -Rest $rest }
     'checklist-read'   { Invoke-ChecklistRead    -Rest $rest }
     'checklist-apply'  { Invoke-ChecklistApply   -Rest $rest }
     'detect-project'   { Invoke-DetectProject    -Rest $rest }
@@ -3942,6 +4440,7 @@ switch ($sub) {
     'setup-constitution' { Invoke-SetupConstitution -Rest $rest }
     'compose-constitution' { Invoke-ComposeConstitution -Rest $rest }
     'constitution-verify' { Invoke-ConstitutionVerify -Rest $rest }
+    'principles-list'     { Invoke-PrinciplesList     -Rest $rest }
     'agent-context-update' { Invoke-AgentContextUpdate -Rest $rest }
     default            { Write-Error "Unknown subcommand: $sub"; exit 1 }
 }