aw-spec-cli 0.1.19 → 0.1.21

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 }
@@ -684,6 +685,8 @@ function Invoke-LaneProbe {
 # (case-insensitive) — (1) specs/ sub-folders (already scaffolded/adopted) and
 # (2) the OKF bundle's Aggregate concepts (the brownfield feature map, resolved by
 # the SAME shared python core the bash twin calls). Empty source 2 on greenfield.
+# Both are scoped to the ACTIVE BOUNDED CONTEXT — source 1 by the directory listed,
+# source 2 by the `bounded_context:` key onboard stamps on every concept it writes.
 # ─────────────────────── context.json (bounded context) ───────────────────
 # Twin of the bash read_context_json_context_directory / feature_base_rel pair. A
 # bounded context is the container a feature lives in — specs/<Context>/<Feature>/ —
@@ -861,13 +864,31 @@ function Invoke-ListFeatures {
     if (-not $bundle) { $bundle = 'knowledge' }
     if (-not [System.IO.Path]::IsPathRooted($bundle)) { $bundle = Join-Path $repo $bundle }
 
+    # The OKF half is scoped to the active bounded context the same way. onboard runs
+    # once per context and stamps each concept it writes, so a bundle that has seen two
+    # runs holds two contexts' aggregates; unfiltered, standing inside one context would
+    # offer the other's features and scaffold them into the wrong tree. Empty when no
+    # context is active, which keeps the flat layout listing everything.
+    $activeCtx = ''
+    if ($baseRel -ne 'specs') { $activeCtx = ($baseRel -split '/')[-1] }
+
     # Best-effort OKF aggregate list (brownfield feature map). Empty on greenfield.
     $okfAggs = @()
     $py = Get-Py; $invpy = Join-Path $PSScriptRoot '..' 'python' 'aw-inventory.py'
     if ($py -and (Test-Path $bundle) -and (Test-Path $invpy)) {
         try {
-            $okfRaw = & $py $invpy list-aggregates --bundle $bundle 2>$null
-            if ($okfRaw) { $okfAggs = @((($okfRaw | ConvertFrom-Json).aggregates)) }
+            # --context only when one is active: Windows PowerShell drops an empty-string
+            # argument to a native command, which would leave --context with no value.
+            $ctxArgs = @(); if ($activeCtx) { $ctxArgs = @('--context', $activeCtx) }
+            $okfRaw = & $py $invpy list-aggregates --bundle $bundle --root $repo @ctxArgs 2>$null
+            if ($okfRaw) {
+                # The FEATURES the map puts on each concept, not the aggregates themselves —
+                # the same list the bash twin reads.
+                $okfJson = $okfRaw | ConvertFrom-Json
+                # An EMPTY `pickable` is an answer (nothing to offer); only its absence
+                # falls back to the raw aggregates.
+                $okfAggs = if ($okfJson.PSObject.Properties.Name -contains 'pickable') { @($okfJson.pickable) } else { @($okfJson.aggregates) }
+            }
         } catch { $okfAggs = @() }
     }
 
@@ -901,7 +922,7 @@ function Invoke-ListFeatures {
             }
         }
     }
-    # Merge OKF-discovered aggregates not already scaffolded under specs/.
+    # Merge the OKF-discovered FEATURES not already scaffolded under specs/.
     foreach ($agg in $okfAggs) {
         $nm = "$($agg.name)".Trim()
         if (-not $nm -or $seen.ContainsKey($nm.ToLower())) { continue }
@@ -944,11 +965,11 @@ function Invoke-SetFeature {
     }
     if (-not $raw) { Write-Error 'set-feature: --feature is required'; exit 1 }
 
-    # Normalize to a PascalCase aggregate identifier (feature = aggregate).
+    # Normalize to a PascalCase identifier.
     $cleaned = ($raw -replace '[^A-Za-z0-9]+', ' ').Trim()
     $feature = ConvertTo-Pascal -In $cleaned
     if ($feature -notmatch '^[A-Za-z][A-Za-z0-9]*$') {
-        Write-Error "set-feature: '$raw' is not a valid feature name (need a letter-led alphanumeric aggregate, e.g. Order)"; exit 1
+        Write-Error "set-feature: '$raw' is not a valid feature name (need a letter-led alphanumeric name, e.g. Order or PatientRegistration)"; exit 1
     }
 
     $repo = Get-RepoRoot
@@ -1449,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
     })
 }
 
@@ -1515,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
@@ -1544,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 ────────────────────────
@@ -1554,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
@@ -2393,6 +2441,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)
@@ -2430,6 +2481,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 { @() })
         })
@@ -2448,16 +2509,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
@@ -2471,7 +2532,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 {
@@ -2940,26 +3029,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
@@ -3086,6 +3190,337 @@ 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
+
+stamped = []
+if stamp and current is not None and 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 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 stamped:
+    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 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 = ''
@@ -3548,12 +3983,24 @@ function Invoke-CrMergeCheck {
     # 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] }
-    })
+    # aw-crstate owns the test, for both shells and all three readers of 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.
+    $mergedOpen = @()
+    $pyMerged = Get-Py
+    $crstate = Join-Path $PSScriptRoot '..' 'python' 'aw-crstate.py'
+    if ($pyMerged -and (Test-Path $crstate)) {
+        try {
+            $line = (& $pyMerged $crstate 'merged-open' '--cr' $crId '--feature-dir' $fd '--context-dir' $ctx | Select-Object -First 1)
+            if ($line) { $mergedOpen = @(($line | ConvertFrom-Json).blocking) }
+        } catch {
+            $mergedOpen = @([pscustomobject]@{ cr_id = '(merged-open check failed)'; blocking = $true })
+        }
+    } else {
+        $mergedOpen = @([pscustomobject]@{ cr_id = '(merged-open check unavailable)'; blocking = $true })
+    }
 
     Write-Json ([ordered]@{
         ok = $true; cr_id = $crId; wave = $wave
@@ -3587,6 +4034,7 @@ 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
@@ -3600,12 +4048,22 @@ function Invoke-CrRecallCheck {
         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.
     $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)'
+    $pyMerged = Get-Py
+    $crstate = Join-Path $PSScriptRoot '..' 'python' 'aw-crstate.py'
+    if ($pyMerged -and (Test-Path $crstate)) {
+        try {
+            $line = (& $pyMerged $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
+            }
+        } catch { }
     }
 
     $wave = if (Test-Path $crDir) { Get-WaveOf $crDir } else { 1 }
@@ -3649,14 +4107,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.
@@ -3667,14 +4176,27 @@ function Get-FileSha {
 
 function Invoke-PlanGateStamp {
     param([string[]]$Rest)
-    $fdArg = ''; $specVersion = ''; $mode = 'master'
+    $fdArg = ''; $specVersion = ''; $mode = 'master'; $verdict = 'conformant'; $planGaps = '0'; $routedRaw = '[]'
     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] }
+            { $_ -in '--verdict','-Verdict' }          { $verdict = $Rest[++$i] }
+            { $_ -in '--plan-gaps','-PlanGaps' }       { $planGaps = $Rest[++$i] }
+            { $_ -in '--routed','-Routed' }            { $routedRaw = $Rest[++$i] }
         }
     }
+    # An unrecognised verdict is recorded as `gaps`, the one that refuses.
+    $verdict = "$verdict".Trim()
+    if ($verdict -notin @('conformant','routed-gaps','gaps')) { $verdict = 'gaps' }
+    $planGapCount = 0
+    if (-not [int]::TryParse("$planGaps", [ref]$planGapCount)) { $planGapCount = 0 }
+    $routed = @()
+    try {
+        $parsedRouted = ConvertFrom-Json -InputObject $(if ("$routedRaw".Trim()) { $routedRaw } else { '[]' }) -NoEnumerate -ErrorAction Stop
+        $routed = @($parsedRouted | ForEach-Object { "$_" })
+    } catch { $routed = @() }
     $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
@@ -3697,19 +4219,24 @@ function Invoke-PlanGateStamp {
         gated        = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
         gate_mode    = $mode
         spec_version = $specVersion.Trim()
+        verdict      = $verdict
+        plan_gaps    = $planGapCount
+        routed_gaps  = @($routed)
         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.')
+        note         = ('Written by every master-mode analyze-plan run. It records the bytes that were ' +
+                        'checked against each other and the verdict on them, 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: moved bytes or verdict `gaps` ' +
+                        'refuse; `routed-gaps` lists what /appweaver specify still has to lift.')
     }
     $p = Join-Path $fd '.aw-plan-gate.json'
-    ($rec | ConvertTo-Json -Depth 6) + "`n" | Set-Content -LiteralPath $p -NoNewline -Encoding utf8
+    (ConvertTo-Json -InputObject $rec -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)
+        spec_version = $rec.spec_version; verdict = $verdict; plan_gaps = $planGapCount
+        routed_gaps = $routed.Count; hashed = @($plans.Keys | Sort-Object)
         count = $plans.Count; ok = $true
     })
 }
@@ -3730,17 +4257,27 @@ function Invoke-PlanGateCheck {
     }
     $out = [ordered]@{
         file = (ConvertTo-RepoRelative -Path $p -RepoRoot $repo); tracked = [bool]$rec
-        gate_fresh = $false; spec_moved = $false; model_moved = $false
+        gate_fresh = $false; verdict = ''; may_generate = $true; plan_gaps = 0
+        routed_gaps = @(); routed_csv = ''; 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'
+        $out.reason = 'no .aw-plan-gate.json — this feature has not been through analyze-plan in master mode since the gate began leaving a receipt'
     } else {
-        $out.gated = [string]$rec.gated
+        # ConvertFrom-Json turns an ISO timestamp into a DateTime; render it back in the
+        # form the receipt was written in, as the bash twin reports it.
+        $out.gated = $(if ($rec.gated -is [datetime]) { $rec.gated.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ') } else { [string]$rec.gated })
         $out.spec_version = [string]$rec.spec_version
+        # A receipt from before the verdict existed was only ever written on a clean pass.
+        $out.verdict = $(if ("$($rec.verdict)") { [string]$rec.verdict } else { 'conformant' })
+        $gapCount = 0
+        if ($null -ne $rec.plan_gaps) { [void][int]::TryParse("$($rec.plan_gaps)", [ref]$gapCount) }
+        $out.plan_gaps = $gapCount
+        $out.routed_gaps = @(@($rec.routed_gaps) | Where-Object { $null -ne $_ } | ForEach-Object { "$_" })
+        $out.routed_csv = ($out.routed_gaps -join '; ')
         $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
@@ -3755,19 +4292,39 @@ function Invoke-PlanGateCheck {
         $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 {
+        # Moved bytes refuse whatever the verdict was; unmoved bytes refuse only on `gaps`.
+        $out.may_generate = ($out.gate_fresh -and $out.verdict -ne 'gaps')
+        if (-not $out.gate_fresh) {
             $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 '; ')
+            $out.reason = 'since analyze-plan checked them on {0}: {1}' -f $out.gated, ($bits -join '; ')
+        } elseif ($out.verdict -eq 'gaps') {
+            $n = $(if ($out.plan_gaps) { $out.plan_gaps } else { 'some' })
+            $out.reason = 'analyze-plan on {0} left {1} gap(s) a plan rewrite closes, unrepaired' -f $out.gated, $n
+        } elseif ($out.verdict -eq 'routed-gaps') {
+            $out.reason = 'the spec, the model and every gated plan are byte-identical to what analyze-plan checked on {0}; it left {1} gap(s) only /appweaver specify can close: {2}' -f $out.gated, $out.routed_gaps.Count, $out.routed_csv
+        } else {
+            $out.reason = 'the spec, the model and every gated plan are byte-identical to what analyze-plan passed on {0}' -f $out.gated
         }
     }
     Write-Json $out
 }
 
+# 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.
+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
 # deterministic twin of cr-archive's active_version.json bump. close-delta calls
 # this with the version cr-archive just computed, so all THREE carriers of the
@@ -3897,6 +4454,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 }
@@ -3905,8 +4464,10 @@ 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 }
     'checklist-read'   { Invoke-ChecklistRead    -Rest $rest }
     'checklist-apply'  { Invoke-ChecklistApply   -Rest $rest }
     'detect-project'   { Invoke-DetectProject    -Rest $rest }