aw-spec-cli 0.1.18 → 0.1.19

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

@@ -20,15 +20,39 @@
 $ErrorActionPreference = 'Stop'
 
 # ─────────────────────────── shared helpers ────────────────────────────────
+#
+# A `[` or `]` ANYWHERE IN THE ROOT REFUSES THE RUN, in both shells. Those two characters
+# are a wildcard character class to PowerShell's `-Path` family and to a shell/Python
+# glob, so under such a root a path test answers about a DIFFERENT path — `…/a[b]/x` is
+# looked up as `…/ab/x` — and an enumeration quietly returns nothing. The kit resolves
+# hundreds of paths against this root, and the failure mode is not an error but a wrong
+# answer: a gate that finds no delta reports a clean tree, and a merge that finds no
+# section merges nothing and says it succeeded.
+#
+# The per-call fixes are in (-LiteralPath on every enumeration here; glob.escape on every
+# pattern's directory in the bash twin), and they cover every site the kit resolves through
+# a pattern. What they cannot cover is the ~150 plain existence tests, and a half-guarded
+# root is worse than a refused one because it looks like it works. So the root itself is
+# the gate, checked once, naming the path.
+function Assert-UnbracketedRoot {
+    param([string]$Root)
+    if ($Root -match '[\[\]]') {
+        Write-Error ("aw-spec: this repository's path contains '[' or ']' — $Root`n" +
+                     "aw-spec: those characters are a wildcard character class to the path APIs this kit uses (PowerShell -Path, shell and Python globs), so file lookups would silently resolve to a different path or to nothing at all, and a gate that finds nothing reports success. Move or rename the checkout so no directory in its path contains a square bracket, then re-run.")
+        exit 1
+    }
+    return $Root
+}
+
 function Get-RepoRoot {
     $dir = (Get-Location).Path
     while ($true) {
-        if (Test-Path (Join-Path $dir '.appweaver')) { return $dir }
+        if (Test-Path -LiteralPath (Join-Path $dir '.appweaver')) { return (Assert-UnbracketedRoot $dir) }
         $parent = Split-Path $dir -Parent
         if ([string]::IsNullOrEmpty($parent) -or $parent -eq $dir) { break }
         $dir = $parent
     }
-    return (Resolve-Path (Join-Path $PSScriptRoot '..' '..' '..')).Path
+    return (Assert-UnbracketedRoot (Resolve-Path -LiteralPath (Join-Path $PSScriptRoot '..' '..' '..')).Path)
 }
 
 function ConvertTo-RepoRelative {
@@ -621,7 +645,13 @@ function Invoke-LaneVerify {
     $fwd = @()
     for ($i = 0; $i -lt $Rest.Count; $i++) {
         switch ($Rest[$i]) {
-            '--require'             { $fwd += '--require'; $fwd += $Rest[++$i] }
+            # An EMPTY --require is "any lane will do" and is dropped rather than
+            # forwarded: the phase needs a declaration to work from, not a lane of a
+            # particular kind. A workflow that includes lane-gate cannot omit an
+            # argument conditionally — the include's `with` map is rendered whole —
+            # so an empty value is the only way it can say this, and argparse rejects
+            # one against --require's choices. Every other check stays armed.
+            '--require'             { $v = $Rest[++$i]; if ("$v".Trim()) { $fwd += '--require'; $fwd += $v } }
             # --flag=value: --command carries a phase name that starts with '/'.
             '--command'             { $fwd += ('--command=' + $Rest[++$i]) }
             '--allow-missing-root'  { $fwd += '--allow-missing-root' }
@@ -854,15 +884,18 @@ function Invoke-ListFeatures {
                 dir           = "$baseRel/$($d.Name)"
                 source        = 'spec'
                 has_spec      = (Test-Path (Join-Path $d.FullName 'spec.md'))
-                # 'design*.md', NOT 'design.*.md': the second dot made this miss the single
-                # `design.md` the framework actually produces (it only matched the retired
-                # design.domain.md / design.technical.md family). Informational count only.
-                # -like, not -Filter: -Filter delegates to the platform's filesystem matcher
-                # (which on Windows also honours 8.3 short names), so it is not guaranteed to
-                # agree with the bash twin's glob. -like is PowerShell's own engine — same
-                # result on every OS, which is what keeps the two scripts provably in parity.
-                design_docs   = @(Get-ChildItem -Path $d.FullName -File -ErrorAction SilentlyContinue |
-                                  Where-Object { $_.Name -like 'design*.md' }).Count
+                # HOW MANY LANE PLANS THIS FEATURE HAS. Counted by NAME, not by pattern:
+                # the documents are backend-plan.md / frontend-plan.md, and the legacy pair
+                # design.md / design.ui.md that feature-paths still resolves under the same
+                # keys for a tree adopted before the rename. The old `design*.md` match
+                # counted neither of the current names, so this was structurally 0 on every
+                # feature the framework produces today — a field that could only ever be
+                # wrong. Informational only; no workflow reads it.
+                #
+                # -LiteralPath on the Join-Path result: the feature directory comes from the
+                # repo's own tree and `-Path` would read a `[` in it as a wildcard class.
+                plan_docs     = @('backend-plan.md','frontend-plan.md','design.md','design.ui.md' |
+                                  Where-Object { Test-Path -LiteralPath (Join-Path $d.FullName $_) -PathType Leaf }).Count
                 version       = $ver
                 active_change = $activeChange
             }
@@ -880,11 +913,15 @@ function Invoke-ListFeatures {
             has_spec      = $false
             adopted       = $false
             concept_path  = "$($agg.concept_path)"
-            design_docs   = 0
+            plan_docs     = 0
             version       = ''
             active_change = ''
         }
     }
+    # `design_docs` is kept as a same-value ALIAS of plan_docs. The key is part of this
+    # op's published shape, so dropping it would break a reader outside the kit for no
+    # gain; what it reports is now the plan pair rather than a pattern that matched nothing.
+    foreach ($f in $features) { $f['design_docs'] = $f['plan_docs'] }
     # select_options = merged names + (injected new --preselect) + sentinel.
     $opts = @($names)
     if ($preselect -and (-not $seen.ContainsKey($preselect.ToLower()))) { $opts += $preselect }
@@ -926,6 +963,33 @@ function Invoke-SetFeature {
     if (Test-IsContextDir -Dir $featureDir) {
         Write-Error "set-feature: refusing — '$featureDirRel' is a bounded context, not a feature. Run /appweaver select-bounded-context $feature first, then select-feature."; exit 1
     }
+    # AND THE SAME REFUSAL FOR A CONTEXT THAT IS MERELY EMPTY. The test above asks what a
+    # directory CONTAINS, so a context created by select-bounded-context and not yet
+    # populated — no domain-model.md, no feature inside it — passes it and is taken as a
+    # feature, which writes spec.md into it and orphans every feature meant to live there.
+    # Emptiness cannot be told from "a new feature directory" by looking at the directory,
+    # so the question asked here is the one list-contexts asks instead: is this repo USING
+    # bounded contexts, and is none of them active? In that state a target directly under
+    # specs/ is outside every context and cannot be the feature the caller meant — which is
+    # exactly the state `select-feature` refuses via scope_ok, restated at the point of the
+    # write so no other caller can walk past it.
+    if ($baseRel -eq 'specs' -and -not (Test-Path (Join-Path $featureDir 'spec.md'))) {
+        $specsRoot = Join-Path $repo 'specs'
+        $otherContexts = @()
+        if (Test-Path $specsRoot) {
+            foreach ($d in (Get-ChildItem -LiteralPath $specsRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
+                if ($d.Name -eq $feature) { continue }
+                # A directory with its own spec.md is a FEATURE (the flat pre-context
+                # layout); one without is a context. Only the latter means contexts are in
+                # use here.
+                if (-not (Test-Path (Join-Path $d.FullName 'spec.md'))) { $otherContexts += $d.Name }
+            }
+        }
+        if ($otherContexts.Count -gt 0) {
+            $names = ($otherContexts -join ', ')
+            Write-Error "set-feature: refusing — this repository uses bounded contexts ($names) and none is active, so '$featureDirRel' would be created outside every one of them. If $feature is itself a bounded context, run /appweaver select-bounded-context $feature. If it is a feature, run /appweaver select-bounded-context to choose the context that owns it first, then select-feature $feature."; exit 1
+        }
+    }
     $existed = Test-Path $featureDir
     New-Item -ItemType Directory -Force -Path $featureDir | Out-Null
     New-Item -ItemType Directory -Force -Path (Join-Path $repo '.appweaver') | Out-Null
@@ -1040,6 +1104,42 @@ elif op == "activate":
         save(d)
         out["active_change"] = d["active_change"]; out["activated"] = cr
     out["open_changes"] = opens; out["open_count"] = len(opens)
+elif op == "recall":
+    # WITHDRAWS one change: drop it from open_changes and move active_change off it,
+    # WITHOUT bumping the version. That is the whole difference from `close`, and it is
+    # the reason the two are separate ops rather than one with a flag. A version is what a
+    # change SHIPPED as; a recalled change shipped nothing, so bumping would burn a number
+    # on work that was never merged and leave the spine claiming a release that does not
+    # exist. Everything else is identical — the same membership edit, the same fallback
+    # for active_change — so a recall and a close leave the ledger in the same SHAPE and
+    # only the number tells them apart.
+    #
+    # Refusing an untracked id is the point of this op, not a nicety: recall archives
+    # documents, so acting on an id the ledger does not know would move a directory on the
+    # strength of a typo. `close` cannot afford the same strictness (it is also the
+    # migration path for state written before open_changes existed); recall can, because
+    # every change it can reach was opened by specify.
+    prev = d["version"]
+    opens = [c for c in (d.get("open_changes") or []) if c]
+    if not opens and d.get("active_change"):
+        opens = [d["active_change"]]          # state written before open_changes existed
+    target = cr or d.get("active_change", "")
+    if not target:
+        out["ok"] = False
+        out["error"] = "no change named and none is active on this feature"
+    elif target not in opens:
+        out["ok"] = False
+        out["error"] = ("'%s' is not an open change on this feature (open: %s)"
+                        % (target, ", ".join(opens) or "none"))
+    else:
+        opens.remove(target)
+        d["open_changes"] = opens
+        d["active_change"] = opens[-1] if opens else ""
+        save(d)
+        out["recalled_change"] = target
+    out["version"] = d["version"]; out["previous"] = prev
+    out["active_change"] = d.get("active_change", "")
+    out["open_changes"] = opens; out["open_count"] = len(opens)
 elif op == "close":
     # Closes ONE change by id (falling back to active_change when none is named, which
     # is the pre-parallel caller). The version bumps once per change materialized, and
@@ -1250,7 +1350,7 @@ function Get-ProjectMarkers {
     $topPrune = @('.appweaver', 'guardrails', 'foundations', 'specs', '.git')
     $names = @('*.sln','*.csproj','package.json','pom.xml','build.gradle','build.gradle.kts','go.mod','Cargo.toml','pyproject.toml')
     $out = @(
-        Get-ChildItem -Path $Start -Recurse -File -Include $names -ErrorAction SilentlyContinue |
+        Get-ChildItem -LiteralPath $Start -Recurse -File -Include $names -ErrorAction SilentlyContinue |
             ForEach-Object { $_.FullName.Substring($Repo.Length).TrimStart('\','/') -replace '\\','/' } |
             Where-Object {
                 $seg = $_.Split('/')
@@ -1337,7 +1437,7 @@ function Get-FoundationDirs {
     if (Test-Path $root) {
         foreach ($s in (Get-ChildItem -Directory $root -ErrorAction SilentlyContinue)) {
             foreach ($d in (Get-ChildItem -Directory $s.FullName -ErrorAction SilentlyContinue)) {
-                if (-not (Get-ChildItem -Path $d.FullName -Filter '*.pack.txt' -File -ErrorAction SilentlyContinue)) { continue }
+                if (-not (Get-ChildItem -LiteralPath $d.FullName -Filter '*.pack.txt' -File -ErrorAction SilentlyContinue)) { continue }
                 $out += [pscustomobject]@{ Name = $d.Name; Stack = $s.Name; Dir = $d.FullName; Rel = "foundations/$($s.Name)/$($d.Name)" }
             }
         }
@@ -1454,7 +1554,7 @@ 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 -Path (Join-Path $out 'src') -Recurse -Filter 'ApplicationDbContext.cs' -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
+    $ctx = Get-ChildItem -LiteralPath (Join-Path $out 'src') -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
@@ -1923,15 +2023,15 @@ function Invoke-FindHostProject {
     if (-not $svcRoot) { $svcRoot = 'src' }
     $eco = Get-LaneField -Field 'backend_ecosystem'
     $searched = $svcRoot.TrimEnd('/')
-    $prog = Get-ChildItem -Path (Join-Path $repo ($svcRoot.TrimEnd('/'))) -Recurse -Filter 'Program.cs' -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
+    $prog = Get-ChildItem -LiteralPath (Join-Path $repo ($svcRoot.TrimEnd('/'))) -Recurse -Filter 'Program.cs' -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
     if (-not $prog) {
-        $prog = Get-ChildItem -Path $repo -Recurse -Filter 'Program.cs' -ErrorAction SilentlyContinue |
+        $prog = Get-ChildItem -LiteralPath $repo -Recurse -Filter 'Program.cs' -ErrorAction SilentlyContinue |
             Where-Object { $_.FullName -notmatch '[/\\](\.git|guardrails|foundations|specs|\.appweaver|obj|bin)[/\\]' } |
             Select-Object -First 1 -ExpandProperty FullName
     }
     if (-not $prog) { Write-Json ([ordered]@{ found = $false; program_cs = ''; project_dir = ''; csproj = ''; ecosystem = $eco; searched = $searched }); return }
     $pdir = Split-Path $prog -Parent
-    $csproj = Get-ChildItem -Path $pdir -Filter *.csproj -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
+    $csproj = Get-ChildItem -LiteralPath $pdir -Filter *.csproj -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
     Write-Json ([ordered]@{ found = $true; program_cs = $prog; project_dir = $pdir; csproj = $(if ($csproj) { $csproj } else { '' }); ecosystem = $eco; searched = $searched })
 }
 
@@ -2241,8 +2341,8 @@ function Invoke-BuildCompile {
 
     # No declaration: the historic first-match-wins ladder, unchanged.
     $tool = 'none'; $ran = $false; $ok = $true; $cmd = ''; $log = ''
-    $hasSln = @(Get-ChildItem -Path $repo -Filter *.sln -File -ErrorAction SilentlyContinue).Count -gt 0
-    $hasCsproj = @(Get-ChildItem -Path (Join-Path $repo 'src') -Filter *.csproj -Recurse -ErrorAction SilentlyContinue).Count -gt 0
+    $hasSln = @(Get-ChildItem -LiteralPath $repo -Filter *.sln -File -ErrorAction SilentlyContinue).Count -gt 0
+    $hasCsproj = @(Get-ChildItem -LiteralPath (Join-Path $repo 'src') -Filter *.csproj -Recurse -ErrorAction SilentlyContinue).Count -gt 0
     if ($hasSln -or $hasCsproj) {
         $tool = 'dotnet'
         if (Get-Command dotnet -ErrorAction SilentlyContinue) {
@@ -2293,8 +2393,8 @@ function Invoke-TestRun {
 
     $tool = 'none'; $ran = $false; $ok = $true; $cmd = ''; $log = ''
     $matched = $false; $scoped = $false; $fenceGreen = $false; $filter = ''
-    $hasSln = @(Get-ChildItem -Path $repo -Filter *.sln -File -ErrorAction SilentlyContinue).Count -gt 0
-    $hasCsproj = @(Get-ChildItem -Path $repo -Filter *.csproj -Recurse -ErrorAction SilentlyContinue).Count -gt 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)
 
     # A DECLARED lane model answers this the same way it answers build-compile, and for
@@ -2409,8 +2509,8 @@ function Invoke-RunMigrate {
     $svcDir = Join-Path $repo ($svcRoot.TrimEnd('/'))
 
     $tool = 'none'; $ran = $false; $ok = $true; $cmd = ''; $log = ''
-    $hasSln = @(Get-ChildItem -Path $repo -Filter *.sln -File -ErrorAction SilentlyContinue).Count -gt 0
-    $hasCsproj = @(Get-ChildItem -Path $svcDir -Filter *.csproj -Recurse -ErrorAction SilentlyContinue).Count -gt 0
+    $hasSln = @(Get-ChildItem -LiteralPath $repo -Filter *.sln -File -ErrorAction SilentlyContinue).Count -gt 0
+    $hasCsproj = @(Get-ChildItem -LiteralPath $svcDir -Filter *.csproj -Recurse -ErrorAction SilentlyContinue).Count -gt 0
     $efOk = $false
     if (($hasSln -or $hasCsproj) -and (Get-Command dotnet -ErrorAction SilentlyContinue)) {
         Push-Location $repo; try { dotnet ef --version *> $null; $efOk = ($LASTEXITCODE -eq 0) } catch { $efOk = $false } finally { Pop-Location }
@@ -2418,10 +2518,10 @@ function Invoke-RunMigrate {
     if ($efOk) {
         # Prefer *Service.csproj (API host with ApplicationDbContext); fall back to first
         # non-AppHost/Web/ServiceDefaults/test project under the service lane's root.
-        $project = Get-ChildItem -Path $svcDir -Filter '*.Service.csproj' -Recurse -ErrorAction SilentlyContinue |
+        $project = Get-ChildItem -LiteralPath $svcDir -Filter '*.Service.csproj' -Recurse -ErrorAction SilentlyContinue |
             Select-Object -First 1 -ExpandProperty FullName
         if (-not $project) {
-            $project = Get-ChildItem -Path $svcDir -Filter '*.csproj' -Recurse -ErrorAction SilentlyContinue |
+            $project = Get-ChildItem -LiteralPath $svcDir -Filter '*.csproj' -Recurse -ErrorAction SilentlyContinue |
                 Where-Object { $_.FullName -notmatch 'AppHost|ServiceDefaults|\.Web\.|Tests' } |
                 Select-Object -First 1 -ExpandProperty FullName
         }
@@ -2495,6 +2595,23 @@ function Set-HeaderStamp {
     Set-Content -Path $Path -Value $text -Encoding UTF8 -NoNewline
 }
 
+# Read one '**Name**: value' header back out of a document — the counterpart of
+# Set-HeaderStamp, for the case where one document's header is the SOURCE of another's.
+# An UNFILLED template placeholder reads as absent: a header still carrying '[vX.Y]' or
+# '[DATE]' states nothing, and copying that bracket forward would spread the placeholder
+# instead of a value. Any trailing '<!-- … -->' the template keeps beside the value is
+# stripped, so the caller gets the value and not the explanation of it.
+# Twin of bash _read_header.
+function Get-MdHeader {
+    param([string]$Path, [string]$Name)
+    if (-not (Test-Path $Path)) { return '' }
+    $m = [regex]::Match((Get-Content $Path -Raw), "(?m)^\*\*$([regex]::Escape($Name))\*\*:[ \t]*(.*)$")
+    if (-not $m.Success) { return '' }
+    $val = ([regex]::Replace($m.Groups[1].Value, '<!--.*', '')).Trim()
+    if ($val.StartsWith('[') -and $val.EndsWith(']')) { return '' }
+    return $val
+}
+
 # The highest wave among the delta models open in a context, or 1 when none is. This is
 # the DEFAULT for a new delta: parallel with whatever is in flight, never implicitly
 # sequenced behind it.
@@ -2524,7 +2641,7 @@ function Get-WaveOf {
 function Get-MaxOpenWave {
     param([string]$ContextDir)
     $best = 0
-    foreach ($f in @(Get-ChildItem -Path $ContextDir -Filter 'domain-model.*.delta.md' -File -ErrorAction SilentlyContinue)) {
+    foreach ($f in @(Get-ChildItem -LiteralPath $ContextDir -Filter 'domain-model.*.delta.md' -File -ErrorAction SilentlyContinue)) {
         $t = Get-Content $f.FullName -Raw -ErrorAction SilentlyContinue
         if ($t -match '(?m)^\*\*Wave\*\*:\s*(\d+)') { $w = [int]$Matches[1]; if ($w -gt $best) { $best = $w } }
     }
@@ -2552,7 +2669,7 @@ function Invoke-ContextPaths {
     $context = if ($ctxRel -eq 'specs') { '' } else { Split-Path $ctxRel -Leaf }
     $master = Join-Path $ctx 'domain-model.md'
     $pending = @(); $files = @(); $waves = @()
-    foreach ($f in @(Get-ChildItem -Path $ctx -Filter 'domain-model.*.delta.md' -File -ErrorAction SilentlyContinue | Sort-Object Name)) {
+    foreach ($f in @(Get-ChildItem -LiteralPath $ctx -Filter 'domain-model.*.delta.md' -File -ErrorAction SilentlyContinue | Sort-Object Name)) {
         $cr = $f.Name.Substring('domain-model.'.Length)
         $cr = $cr.Substring(0, $cr.Length - '.delta.md'.Length)
         $wave = 1
@@ -2659,7 +2776,7 @@ function Invoke-CrList {
     $rows = @()
     $changesDir = Join-Path $fd 'changes'
     if (Test-Path $changesDir) {
-        foreach ($d in @(Get-ChildItem -Path $changesDir -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
+        foreach ($d in @(Get-ChildItem -LiteralPath $changesDir -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
             if ($d.Name -eq 'archive') { continue }
             $dspec  = Join-Path $d.FullName 'delta-spec.md'
             $dmodel = Join-Path $ctx ("domain-model." + $d.Name + ".delta.md")
@@ -2718,6 +2835,10 @@ function Invoke-CrList {
     }
     Write-Json ([ordered]@{
         changes = @($rows); ids = @($rows | ForEach-Object { $_.cr_id }); count = $rows.Count
+        # The same ids as one readable string, for an operator message. A list renders as
+        # its JSON in a rendered string, which is right for a payload and wrong for a
+        # sentence.
+        ids_csv = (@($rows | ForEach-Object { $_.cr_id }) -join ', ')
         select_options = @($opts); matched_label = $matched
         main_label = $(if ($incMain) { $mainLabel } else { '' })
         new_label = $(if ($incNew) { $newLabel } else { '' })
@@ -2755,7 +2876,7 @@ function Invoke-CrPaths {
     $master = Join-Path $ctx 'domain-model.md'
     $wave = [int](Get-WaveOf -FeatureDir $fd -CrId $crId -Repo $repo)
     $pred = @(); $sib = @(); $predRows = @(); $sibRows = @(); $predSpecs = @()
-    foreach ($f in @(Get-ChildItem -Path $ctx -Filter 'domain-model.*.delta.md' -File -ErrorAction SilentlyContinue | Sort-Object Name)) {
+    foreach ($f in @(Get-ChildItem -LiteralPath $ctx -Filter 'domain-model.*.delta.md' -File -ErrorAction SilentlyContinue | Sort-Object Name)) {
         $other = $f.Name.Substring('domain-model.'.Length)
         $other = $other.Substring(0, $other.Length - '.delta.md'.Length)
         if ($other -eq $crId) { continue }
@@ -2766,9 +2887,18 @@ function Invoke-CrPaths {
         # A change's model delta sits at CONTEXT level and its delta-spec at FEATURE level,
         # so the spec of another open change is found by walking the context's features
         # rather than assuming it belongs to this one.
+        #
+        # The walk is EXPLICIT and every test is -LiteralPath, so no part of the repo's own
+        # path is ever read as a pattern: -Path treats [ and ] as a wildcard character
+        # class, which would silently return nothing for a context living under a directory
+        # whose name contains either. Enumerating the feature directories and testing one
+        # literal path each keeps this a provable twin of the bash glob on every platform.
         $sRel = ''
-        $sHit = @(Get-ChildItem -Path (Join-Path $ctx ('*/changes/{0}/delta-spec.md' -f $other)) -File -ErrorAction SilentlyContinue | Sort-Object FullName)
-        if ($sHit.Count -gt 0) { $sRel = ConvertTo-RepoRelative -Path $sHit[0].FullName -RepoRoot $repo }
+        $sHit = @(Get-ChildItem -LiteralPath $ctx -Directory -ErrorAction SilentlyContinue |
+                  ForEach-Object { Join-Path $_.FullName "changes/$other/delta-spec.md" } |
+                  Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } |
+                  Sort-Object)
+        if ($sHit.Count -gt 0) { $sRel = ConvertTo-RepoRelative -Path $sHit[0] -RepoRoot $repo }
         $row = [ordered]@{ cr_id = $other; file = $rel; wave = $w; delta_spec = $sRel }
         if ($w -lt $wave) {
             $pred += $rel; $predRows += $row
@@ -2794,6 +2924,17 @@ function Invoke-CrPaths {
         predecessor_docs = @($pred + $predSpecs)
         # Same or higher wave = nothing orders it against this one. Visible, never assumed.
         sibling_files = @($sib); siblings = @($sibRows); sibling_count = $sib.Count
+        # EVERYTHING A PLANNER SHOULD SEE, in one list, for the same one-var reason.
+        # Siblings belong in it as much as predecessors do: a planner told "do not assume a
+        # same-wave delta, and say so where one touches the same aggregate" cannot name an
+        # overlap it was never shown, and the gate one stage later raises a finding for the
+        # silence. Their MODEL deltas only — the aggregate a sibling touches is what makes
+        # it an overlap, and their delta-specs would double the payload to say nothing more.
+        related_docs = @($pred + $predSpecs + $sib)
+        # Who is who, as text for a prompt. The file list alone cannot say which entries
+        # are committed to landing first and which are merely open beside this one.
+        predecessor_ids = (@($predRows | ForEach-Object { '{0} (wave {1})' -f $_.cr_id, $_.wave }) -join ', ')
+        sibling_ids     = (@($sibRows  | ForEach-Object { '{0} (wave {1})' -f $_.cr_id, $_.wave }) -join ', ')
     })
 }
 
@@ -2842,7 +2983,7 @@ function Invoke-CrOverlap {
     $wave = [int](Get-WaveOf -FeatureDir $fd -CrId $crId -Repo $repo)
     $mine = @(Get-DeltaAggregates -Text $mineTxt)
     $rows = @(); $parts = @(); $npred = 0; $nsib = 0; $nsucc = 0
-    foreach ($f in @(Get-ChildItem -Path $ctx -Filter 'domain-model.*.delta.md' -File -ErrorAction SilentlyContinue | Sort-Object Name)) {
+    foreach ($f in @(Get-ChildItem -LiteralPath $ctx -Filter 'domain-model.*.delta.md' -File -ErrorAction SilentlyContinue | Sort-Object Name)) {
         $other = $f.Name.Substring('domain-model.'.Length)
         $other = $other.Substring(0, $other.Length - '.delta.md'.Length)
         if ($other -eq $crId) { continue }
@@ -2863,6 +3004,9 @@ function Invoke-CrOverlap {
     }
     Write-Json ([ordered]@{
         cr_id = $crId; wave = $wave; aggregates = @($mine)
+        # The same names as one readable string, for a prompt. A list renders as its JSON
+        # in a rendered string, which is right for a payload and wrong for a sentence.
+        aggregates_csv = (@($mine) -join ', ')
         overlaps = @($rows); overlap_count = $rows.Count
         predecessor_overlaps = $npred; sibling_overlaps = $nsib
         successor_overlaps = $nsucc
@@ -2890,7 +3034,26 @@ function Invoke-CrActivate {
     if (-not $crId) { Write-Error 'cr-activate: --cr-id is required'; exit 1 }
     $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
     if (-not $fd) { Write-Error 'cr-activate: no feature set and no --feature-dir'; exit 1 }
-    Invoke-ActiveVersion -FeatureDir $fd -Op 'activate' -CrId $crId
+    $out = Invoke-ActiveVersion -FeatureDir $fd -Op 'activate' -CrId $crId
+    $out
+    # A REFUSAL IS AN ERROR, NOT A RESULT — so it leaves through the exit code, like every
+    # other way this command can fail. When the id is not in the ledger nothing moves and
+    # the JSON reports active_change: "", which is precisely what the calling step binds;
+    # an empty active change then reads as "no change" in every condition downstream, and
+    # the run continues against a target it never selected. Refusing here turns that into
+    # the engine's own stop, carrying the message to the operator. Twin of bash cr-activate.
+    #
+    # THIS IS REACHABLE, not defensive: cr-list offers what is on DISK (changes/<id>/ is
+    # the authority for "open") and reports `tracked` separately, so a change whose
+    # directory survived a crashed run is still offered while the ledger has forgotten it.
+    #
+    # `ok` starts true and is flipped only by a refusal, so an EXPLICIT false is the test.
+    $res = $null
+    try { $res = ($out | ConvertFrom-Json) } catch { return }
+    if ($null -ne $res -and $res.PSObject.Properties.Name -contains 'ok' -and -not $res.ok) {
+        Write-Error "cr-activate: $($res.error)"
+        exit 1
+    }
 }
 
 # ─────────────────────────── cr-wave ───────────────────────────────────────
@@ -2906,6 +3069,9 @@ function Invoke-CrWave {
             { $_ -in '--wave','-Wave' } { $wave = $Rest[++$i] }
         }
     }
+    # The whole LABEL arrives when a caller picked from a menu; every cr-* op takes its
+    # first token. A bare id is unchanged by this.
+    $crId = Get-CrIdToken -Raw $crId
     if (-not $crId) { Write-Error 'cr-wave: --cr-id is required'; exit 1 }
     if ($wave -notmatch '^\d+$') { Write-Error 'cr-wave: --wave must be a positive integer'; exit 1 }
     $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
@@ -2932,6 +3098,9 @@ function Invoke-CrSetup {
             { $_ -in '--force','-Force' } { $force = '1' }
         }
     }
+    # Before the generated default, so a menu LABEL passed as --cr-id becomes its id
+    # rather than a directory name with spaces in it. Empty stays empty and is generated.
+    $crId = Get-CrIdToken -Raw $crId
     # A random suffix, not the bare timestamp: two changes opened in the same second
     # would otherwise collide on one id, and with parallel deltas that is reachable.
     if (-not $crId) { $crId = 'CR-' + ((Get-Date).ToUniversalTime().ToString('yyyyMMdd-HHmmss')) + '-' + (Get-RandSuffix) }
@@ -2969,31 +3138,92 @@ function Invoke-CrSetup {
         if ($t) { Copy-Item $t $dmodel } else { New-Item -ItemType File -Force -Path $dmodel | Out-Null }
         $created = $true
     }
-    # Scripts stamp ids, dates and the wave — the model never writes them.
+    # Scripts stamp ids, dates and versions — the model never writes them, and the delta
+    # quality checklists REQUIRE a complete header, so every placeholder the templates
+    # carry has to be filled here or it ships as a literal '[DATE]' / '[vX.Y]'.
+    #
+    # BASE VERSION is the master version this delta is being authored AGAINST, read from
+    # the ledger that was just updated — 'open' does not move the number, so what comes
+    # back is the current one. It is what a rebase check compares against later: a master
+    # that moved between the opening of a change and its merge is a change authored on a
+    # document that no longer exists in that form.
+    #
+    # BASE CONTEXT VERSION is the same idea one level up, and its source is the master
+    # model's own '**Context version**:' header rather than any ledger — there is no
+    # context-level version file (⌛ that, and the close-delta bump that would move the
+    # number, are still to build). While nothing bumps it, every delta reads the same
+    # v1.0; the field is still correct, and it starts carrying real information the moment
+    # something stamps the master.
+    $createdOn = [DateTime]::UtcNow.ToString('yyyy-MM-dd')
+    $baseVersion = ''
+    try { $baseVersion = "$(($avOpen | ConvertFrom-Json).version)" } catch { $baseVersion = '' }
+    if (-not $baseVersion) { $baseVersion = 'v1.0' }
+    if (-not $baseVersion.StartsWith('v')) { $baseVersion = "v$baseVersion" }
+    $baseCtx = Get-MdHeader -Path (Join-Path $ctx 'domain-model.md') -Name 'Context version'
+    if (-not $baseCtx) { $baseCtx = 'v1.0' }
+    # Both version fields are normalised to the same 'vX.Y' shape. base_version comes from
+    # a machine ledger and baseCtx from a markdown header a human may have written as
+    # '1.0', and a rebase check compares these as strings — two spellings of one version
+    # would read as a move that never happened.
+    if (-not $baseCtx.StartsWith('v')) { $baseCtx = "v$baseCtx" }
+
     Set-HeaderStamp -Path $dspec  -Name 'Wave' -Value $wave
+    Set-HeaderStamp -Path $dspec  -Name 'Created' -Value $createdOn
+    Set-HeaderStamp -Path $dspec  -Name 'Base version' -Value $baseVersion
     Set-HeaderStamp -Path $dmodel -Name 'Wave' -Value $wave
+    Set-HeaderStamp -Path $dmodel -Name 'Created' -Value $createdOn
+    Set-HeaderStamp -Path $dmodel -Name 'Base context version' -Value $baseCtx
 
     Write-Json ([ordered]@{
         cr_id = $crId; cr_dir = $crDir; delta_spec = $dspec
         delta_model = $dmodel; context_dir = (ConvertTo-RepoRelative -Path $ctx -RepoRoot $repo)
         wave = [int]$wave; open_count = $openCount; title = $title; created = $created
+        created_on = $createdOn; base_version = $baseVersion; base_context_version = $baseCtx
     })
 }
 
+# ARCHIVE, in either of the two ways a change leaves the open set.
+#
+#   default   CLOSED — it shipped. The directory is archived and the version bumps, which
+#             is close-delta's whole job and the behaviour every existing caller gets.
+#   --recall  WITHDRAWN — it never shipped. The same archive, and NO version bump: a
+#             version records what a change shipped as, and a recalled change shipped
+#             nothing, so bumping would burn a number on work that was never merged.
+#
+# The two were fused until recall-delta needed the archive half on its own, which is why
+# withdrawing a change could not be "archive alone". Splitting them here rather than in
+# each caller keeps ONE place that knows how a change's documents are put away — the
+# directory, and the model delta that lives beside the master rather than inside it.
 function Invoke-CrArchive {
     param([string[]]$Rest)
-    $crId = ''; $fdArg = ''
+    $crId = ''; $fdArg = ''; $recall = $false; $reason = ''
     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] }
+            '--recall' { $recall = $true }
+            '--reason' { $reason = $Rest[++$i] }
         }
     }
+    # A caller that picked from a user_select menu hands over the whole LABEL
+    # ("CR-… · wave 2 · title"), not the id. Every other cr-* op takes the first token;
+    # this one did not, so a label arrived here as a directory name that does not exist
+    # and the archive silently moved nothing.
+    $crId = Get-CrIdToken -Raw $crId
     if (-not $crId) { Write-Error 'cr-archive: --cr-id required'; exit 1 }
     $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
     if (-not $fd) { Write-Error 'cr-archive: no feature set and no --feature-dir'; exit 1 }
+    # THE LEDGER EDIT COMES FIRST, because it is the only step that can REFUSE. `recall`
+    # will not withdraw a change active_version.json does not carry, and a refusal has to
+    # be a no-op: archiving before asking would move the directory and only then report
+    # that the change was never open. `close` cannot refuse, so its side effects are
+    # unchanged by the ordering.
+    $op = if ($recall) { 'recall' } else { 'close' }
+    $av = Invoke-ActiveVersion -FeatureDir $fd -Op $op -CrId $crId | ConvertFrom-Json
+    $ledgerOk = $(if ($null -ne $av.ok) { [bool]$av.ok } else { $true })
+
     $crDir = Join-Path $fd "changes/$crId"; $archRoot = Join-Path $fd 'changes/archive'; $archived = ''
-    if (Test-Path $crDir) {
+    if ($ledgerOk -and (Test-Path $crDir)) {
         New-Item -ItemType Directory -Force -Path $archRoot | Out-Null
         $dest = Join-Path $archRoot $crId
         if (Test-Path $dest) { Remove-Item -Recurse -Force $dest }
@@ -3005,15 +3235,537 @@ function Invoke-CrArchive {
     # file behind would keep showing a landed change as in-flight to every other delta.
     $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
     $dmodel = Join-Path $ctx "domain-model.$crId.delta.md"
-    if (Test-Path $dmodel) {
+    $archivedModel = ''
+    if ($ledgerOk -and (Test-Path $dmodel)) {
         $destDir = Join-Path $archRoot $crId
         New-Item -ItemType Directory -Force -Path $destDir | Out-Null
-        Move-Item -Force $dmodel (Join-Path $destDir 'domain-model.delta.md')
+        $archivedModel = Join-Path $destDir 'domain-model.delta.md'
+        Move-Item -Force $dmodel $archivedModel
+    }
+    # A RECALLED change is marked as such where the evidence will be looked for — inside
+    # its own archive — and the marker is written by the script, not by a model, because
+    # everything on it is a fact the script already holds: the id, the date, and the
+    # reason the caller passed.
+    $marker = ''
+    if ($recall -and $archived) {
+        $marker = Join-Path $archived 'RECALLED.md'
+        $when = [DateTime]::UtcNow.ToString('yyyy-MM-dd')
+        $why  = if ("$reason".Trim()) { "$reason".Trim() } else { '(not stated)' }
+        $body = @(
+            "# RECALLED — $crId", '',
+            "**Recalled**: $when",
+            "**Reason**: $why", '',
+            'This change was WITHDRAWN before it was merged. Its delta documents are archived here',
+            'unchanged; the feature''s spec.md and the context''s domain-model.md never carried it,',
+            'and the version was not bumped — no release shipped this work.', '',
+            'Any code /appweaver implement generated for this change is NOT reverted by a recall.',
+            'Revert it with git if it should not stay.', ''
+        ) -join "`n"
+        [System.IO.File]::WriteAllText($marker, $body)
+    }
+    $out = [ordered]@{
+        # The ledger edit is what can refuse (recall will not touch a change the ledger
+        # does not carry), so its verdict is this command's verdict.
+        ok              = $ledgerOk
+        archived_dir    = $archived
+        archived_model  = $archivedModel
+        recalled        = $recall
+        recall_marker   = $marker
+        version         = $av.version
+        previous        = $av.previous
+        # Which of the two ways it left the open set. Exactly one is ever non-empty.
+        closed_change   = $(if ($av.PSObject.Properties['closed_change'])   { $av.closed_change }   else { '' })
+        recalled_change = $(if ($av.PSObject.Properties['recalled_change']) { $av.recalled_change } else { '' })
+        active_change   = $av.active_change
+        open_changes    = @($av.open_changes)
+        open_count      = $av.open_count
+    }
+    if ($av.PSObject.Properties['error']) { $out['error'] = $av.error }
+    Write-Json $out
+}
+
+# ──────────────────────────── context-version-bump ─────────────────────────
+# Move the BOUNDED CONTEXT's version, the way version-stamp moves a feature's.
+#
+# The model's header has always declared itself script-stamped — '**Context version**:
+# v1.0   <!-- script-stamped; close-delta bumps it when a closing delta touched the
+# model -->' — and specify tells the authoring model not to write it. Nothing wrote it,
+# so every context sat at the template's v1.0 for its whole life and the one instruction
+# the model was given about that field was the only thing keeping it accurate.
+#
+# WHY IT IS A CONTEXT-LEVEL NUMBER. A feature's version says what that feature shipped;
+# the model is shared by every feature in the context, so a change to it is a change to
+# all of them and no single feature's version can record it. The two spines move
+# independently and neither is derived from the other.
+#
+# ONLY WHEN THE MODEL ACTUALLY CHANGED. The caller passes --touched-model; a behaviour-only
+# change closes without moving this number, exactly as it leaves domain-model.md alone.
+# Refusing to bump is reported, not an error — most changes never touch the model.
+function Invoke-ContextVersionBump {
+    param([string[]]$Rest)
+    $fdArg = ''; $touched = $false; $crId = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] }
+            { $_ -in '--cr-id','-CrId' } { $crId = $Rest[++$i] }
+            # Takes a VALUE rather than being a bare flag: a workflow cannot omit an
+            # argument conditionally (an include's arg list is rendered whole), so the
+            # caller always passes it and says true or false. Anything but 'true' is false.
+            '--touched-model' { $touched = ("$($Rest[++$i])".Trim() -eq 'true') }
+        }
     }
-    # Close THIS change in active_version.json (single version source): bump minor + drop
-    # it from open_changes. Other changes on the feature stay open.
-    $av = Invoke-ActiveVersion -FeatureDir $fd -Op 'close' -CrId $crId | ConvertFrom-Json
-    Write-Json ([ordered]@{ ok = $true; archived_dir = $archived; version = $av.version; previous = $av.previous; closed_change = $av.closed_change })
+    # The whole LABEL arrives when a caller picked from a menu; every cr-* op takes its
+    # first token. Here the id only reaches the Change History row, so a label would have
+    # been recorded verbatim rather than failing loudly — the quietest of the family's
+    # inconsistencies, and the reason to close it rather than wait for a caller to hit it.
+    $crId = Get-CrIdToken -Raw $crId
+    $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'context-version-bump: no feature set and no --feature-dir'; exit 1 }
+    $ctx   = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
+    $model = Join-Path $ctx 'domain-model.md'
+
+    $current = Get-MdHeader -Path $model -Name 'Context version'
+    if (-not $current) { $current = 'v1.0' }
+    if (-not $current.StartsWith('v')) { $current = "v$current" }
+
+    $bumped = $false; $next = $current; $reason = ''
+    if (-not (Test-Path $model)) {
+        $reason = 'this feature''s context has no domain-model.md, so there is no context version to move'
+    } elseif (-not $touched) {
+        $reason = 'the closing change carried no model delta, so the context is unchanged'
+    } else {
+        $m = [regex]::Match($current.Trim(), '^v?(\d+)(?:\.(\d+))?')
+        $maj = if ($m.Success) { [int]$m.Groups[1].Value } else { 1 }
+        $mnr = if ($m.Success -and $m.Groups[2].Success) { [int]$m.Groups[2].Value } else { 0 }
+        $next = 'v{0}.{1}' -f $maj, ($mnr + 1)
+        Set-HeaderStamp -Path $model -Name 'Context version' -Value $next
+        $bumped = $true
+        $reason = 'the closing change merged a model delta into this context'
+    }
+    Write-Json ([ordered]@{
+        ok = $true; bumped = $bumped; previous = $current; version = $next
+        model = (ConvertTo-RepoRelative -Path $model -RepoRoot $repo)
+        model_exists = (Test-Path $model)
+        context = (ConvertTo-RepoRelative -Path $ctx -RepoRoot $repo)
+        reason = $reason
+    })
+}
+
+# ───────────────────────────── cr-recall-check ─────────────────────────────
+# The two mechanical refusals recall-delta needs, answered in one call from evidence on
+# disk rather than from anything a model read.
+#
+# MERGED. finalize-delta appends a Change History row carrying the CR id to spec.md, so
+# the id appearing in that file is the on-disk proof the merge ran. A merged change is
+# not recallable: the masters describe behaviour that includes it, and taking it back is
+# document surgery — the remedy is a NEW change that reverses it.
+#
+# DEPENDANTS. A wave is a dependency level: a higher wave is planned and built ON TOP of
+# the lower ones. Withdrawing a lower-wave change therefore strands every open change
+# above it. `depends_on` is stamped nowhere yet, so the wave is the only dependency signal
+# that actually exists, and it is the conservative one — same-wave changes are independent
+# by definition and are never counted here.
+# ───────────────────────────── cr-snapshot ─────────────────────────────────
+# Copy the two MASTERS into changes/<id>/pre-merge/ immediately before finalize-delta
+# rewrites them. The merge is the one act of the CR loop that edits a long-lived
+# hand-curated document in place, and until this existed the only record of what those
+# documents said beforehand was git — a different tool's answer to the question, and
+# unavailable at all if the merge and the commit are not interleaved.
+#
+# WHAT IT IS FOR. A recall after a merge has to put the masters back, and it may only do so
+# when nothing else landed in between — the pre-merge copy is the content to restore and
+# cr-merge-check's base_version comparison is what answers whether restoring is still safe.
+#
+# It is a COPY, not a move, and is overwritten on a re-run: finalize-delta may be attempted
+# more than once (a red downstream fence aborts it), and the snapshot that matters is the
+# one taken by the attempt that actually merged. The manifest records the version and date
+# so a reader can tell which. The snapshot travels WITH the change, so a closed change
+# carries the before-image of the masters it moved, in the archive, forever.
+# Twin of bash cr-snapshot.
+function Invoke-CrSnapshot {
+    param([string[]]$Rest)
+    $crId = ''; $fdArg = ''
+    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] }
+        }
+    }
+    $crId = Get-CrIdToken -Raw $crId
+    if (-not $crId) { Write-Error 'cr-snapshot: --cr-id required'; exit 1 }
+    $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'cr-snapshot: no feature set and no --feature-dir'; exit 1 }
+    $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
+
+    $snap = Join-Path $fd "changes/$crId/pre-merge"
+    if (-not (Test-Path -LiteralPath $snap)) { New-Item -ItemType Directory -Path $snap -Force | Out-Null }
+    $spec  = Join-Path $fd 'spec.md'
+    $model = Join-Path $ctx 'domain-model.md'
+    # Flat names, not the source tree's shape: there are exactly two masters and they live
+    # at different levels, so a nested copy would encode the layout of the day it was taken.
+    [string[]]$copied = @()
+    foreach ($pair in @(@($spec, 'spec.md'), @($model, 'domain-model.md'))) {
+        if (Test-Path -LiteralPath $pair[0] -PathType Leaf) {
+            Copy-Item -LiteralPath $pair[0] -Destination (Join-Path $snap $pair[1]) -Force
+            $copied += $pair[1]
+        }
+    }
+
+    $version = ''
+    $avPath = Join-Path $fd 'active_version.json'
+    if (Test-Path -LiteralPath $avPath) {
+        try { $version = "$((Get-Content $avPath -Raw | ConvertFrom-Json).version)" } catch { $version = '' }
+    }
+
+    $manifest = [ordered]@{
+        cr_id           = $crId
+        taken           = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
+        version         = $version
+        context_version = (Get-MdHeader -Path $model -Name 'Context version')
+        files           = @($copied)
+        sources         = [ordered]@{
+            'spec.md'         = (ConvertTo-RepoRelative -Path $spec  -RepoRoot $repo)
+            'domain-model.md' = (ConvertTo-RepoRelative -Path $model -RepoRoot $repo)
+        }
+        # Stated in the file itself, because the restore is the reader's whole reason for
+        # opening it and the condition on it is not obvious from the content.
+        note = ("Masters as they stood immediately before finalize-delta merged $crId. " +
+                "Restoring is only safe while no other change finalized afterwards — " +
+                "cr-merge-check's base_version comparison is what answers that.")
+    }
+    $mPath = Join-Path $snap 'manifest.json'
+    ($manifest | ConvertTo-Json -Depth 6) | Set-Content -LiteralPath $mPath -Encoding utf8
+
+    Write-Json ([ordered]@{
+        ok = $true; cr_id = $crId
+        dir = (ConvertTo-RepoRelative -Path $snap -RepoRoot $repo)
+        files = @($copied); count = @($copied).Count; version = $version
+        manifest = (ConvertTo-RepoRelative -Path $mPath -RepoRoot $repo)
+    })
+}
+
+# ───────────────────────────── cr-merge-check ──────────────────────────────
+# The two mechanical refusals finalize-delta needs, answered in one call from evidence on
+# disk — the merge-side twin of cr-recall-check below, shaped the same way so the two gates
+# of the CR loop read alike.
+#
+# REBASE. cr-setup stamps '**Base version**:' into the delta-spec when the change opens: the
+# master version the delta was authored AGAINST. If spec.md has moved since — because
+# another change finalized and closed in between — the delta's MODIFIED items name a BEFORE
+# the master no longer says, and merging them is last-writer-wins against work that already
+# landed. Both sides are normalised to 'vX.Y' by cr-setup, so this is an exact string
+# comparison and never a judgement. A delta with no stamped header reports an empty
+# base_version and does NOT block: an absent stamp is no evidence of a move.
+#
+# PREDECESSORS. A wave is a dependency level: a LOWER wave is committed to landing first,
+# and plan puts exactly those deltas in the planner's context as the base this one builds
+# on. Merging out of wave order folds in behaviour assuming a predecessor the masters do not
+# yet carry. depends_on is stamped nowhere, so the wave is the only dependency signal that
+# exists; same-wave changes are independent by definition and are never counted.
+#
+# The scan is CONTEXT-WIDE, matching cr-paths' definition of a predecessor, and reads both
+# halves — the changes/<id>/ directories AND the pending model deltas — because a
+# behaviour-only change has no model delta and would be invisible to a scan of those alone.
+# Twin of bash cr-merge-check.
+function Invoke-CrMergeCheck {
+    param([string[]]$Rest)
+    $crId = ''; $fdArg = ''
+    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] }
+        }
+    }
+    $crId = Get-CrIdToken -Raw $crId
+    if (-not $crId) { Write-Error 'cr-merge-check: --cr-id required'; exit 1 }
+    $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    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 '' }
+        if ($v.StartsWith('v')) { return $v } else { return "v$v" }
+    }
+
+    $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
+    # reports, so the two can never disagree about what the number is.
+    $current = ''
+    $avPath = Join-Path $fd 'active_version.json'
+    if (Test-Path -LiteralPath $avPath) {
+        try { $current = Format-Ver "$((Get-Content $avPath -Raw | ConvertFrom-Json).version)" } catch { $current = '' }
+    }
+    if (-not $current) { $current = Format-Ver (Get-MdHeader -Path (Join-Path $fd 'spec.md') -Name 'Version') }
+
+    # Only a STAMPED base that DISAGREES blocks. No stamp, or no readable current version,
+    # 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 = '' }
+            }
+        }
+    }
+    $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] }
+    })
+
+    Write-Json ([ordered]@{
+        ok = $true; cr_id = $crId; wave = $wave
+        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
+        rebase_needed = $rebaseNeeded
+        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 ', ')
+        # 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))
+    })
+}
+
+function Invoke-CrRecallCheck {
+    param([string[]]$Rest)
+    $crId = ''; $fdArg = ''
+    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] }
+        }
+    }
+    $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
+    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
+    }
+
+    $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 }
+        }
+    }
+
+    $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 } }
+        }
+    }
+    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)
+    })
+}
+
+# ──────────────────── plan-gate-stamp / plan-gate-check ────────────────────
+# THE RECEIPT THAT analyze-plan PASSED, and over WHICH BYTES.
+#
+# implement generates from the lane plans and deliberately does NOT read the spec — its
+# own header says "analyze-plan already conformed the plans to it". That sentence was an
+# assumption about the order the operator ran things in, not a fact anything checked: the
+# lane gates test that the plan FILE EXISTS and nothing more, so `plan` → edit spec.md →
+# `implement` generated from a plan that was never held against the spec it now contradicts.
+#
+# WHY NOT COMPARE THE PLANS' `**Version**:` HEADERS. They cannot answer this. version-stamp
+# moves spec.md, backend-plan.md and frontend-plan.md to the same number in LOCKSTEP at
+# close-delta, whether or not a plan was re-derived — close-delta says so itself ("a plan
+# header stamped here is stating the version the slice ships as, not that the plan was
+# re-derived for it"). Comparing them reads equal always, which is worse than not checking.
+#
+# 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.
+#
+# 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.
+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.
+    param([string]$Path)
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { return '' }
+    return (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLower()
+}
+
+function Invoke-PlanGateStamp {
+    param([string[]]$Rest)
+    $fdArg = ''; $specVersion = ''; $mode = 'master'
+    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] }
+        }
+    }
+    $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
+    })
+}
+
+function Invoke-PlanGateCheck {
+    param([string[]]$Rest)
+    $fdArg = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) { { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] } }
+    }
+    $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
 }
 
 # Stamp a version into the MASTER documents' `**Version**:` headers — the
@@ -3028,14 +3780,16 @@ function Invoke-CrArchive {
 # Only the value moves; any trailing inline comment on the header line is kept.
 function Invoke-VersionStamp {
     param([string[]]$Rest)
-    $ver = ''; $fdArg = ''
+    $ver = ''; $fdArg = ''; $crId = ''
     for ($i = 0; $i -lt $Rest.Count; $i++) {
         switch ($Rest[$i]) {
             { $_ -in '--version','-Version' } { $ver = $Rest[++$i] }
             { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] }
+            { $_ -in '--cr-id','-CrId' } { $crId = $Rest[++$i] }
         }
     }
     if (-not $ver) { Write-Error 'version-stamp: --version required'; exit 1 }
+    $crId = Get-CrIdToken -Raw $crId
     $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
     if (-not $fd) { Write-Error 'version-stamp: no feature set and no --feature-dir'; exit 1 }
     $ver = $ver.Trim()
@@ -3060,8 +3814,45 @@ function Invoke-VersionStamp {
         [System.IO.File]::WriteAllText($p, $out)
         $stamped += $name
     }
+
+    # THE CHANGE HISTORY ROW, completed with the number the headers just took. The row is
+    # found by its CR cell, not by position: rows are appended newest-last and a feature may
+    # carry many, so "the last row" would be right only until two changes were open at once.
+    # Only a cell still reading '(pending)' is written — a row already carrying a version
+    # belongs to a change that closed, and re-stamping it would rewrite history.
+    $rowFilled = $false; $rowWas = ''
+    if ($crId) {
+        $p = Join-Path $fd 'spec.md'
+        if (Test-Path -LiteralPath $p) {
+            $lines = [System.IO.File]::ReadAllLines($p)
+            $changed = $false
+            for ($i = 0; $i -lt $lines.Count; $i++) {
+                if ($changed) { break }
+                $line = $lines[$i]
+                if ($line.Contains($crId) -and $line.TrimStart().StartsWith('|')) {
+                    $cells = $line -split '\|'
+                    if ($cells.Count -gt 2 -and
+                        @('(pending)','pending','—','-','') -contains $cells[1].Trim().ToLower()) {
+                        $rowWas = $cells[1].Trim()
+                        $cells[1] = " $ver "
+                        $lines[$i] = ($cells -join '|')
+                        $changed = $true
+                    }
+                }
+            }
+            if ($changed) {
+                [System.IO.File]::WriteAllLines($p, $lines)
+                $rowFilled = $true
+            }
+        }
+    }
+
     Write-Json ([ordered]@{ ok = $true; version = $ver; stamped = $stamped; unchanged = $unchanged;
-                            missing = $missing; no_header = $noHeader; count = $stamped.Count })
+                            missing = $missing; no_header = $noHeader; count = $stamped.Count
+                            # Whether the merge's pending row was completed. False with a
+                            # --cr-id is the ordinary outcome for a re-run (already filled)
+                            # and for a merge predating the pending convention.
+                            cr_id = $crId; history_row_filled = $rowFilled; history_row_was = $rowWas })
 }
 
 # ─────────────────────────────── main ──────────────────────────────────────
@@ -3107,9 +3898,15 @@ switch ($sub) {
     'cr-activate'      { Invoke-CrActivate       -Rest $rest }
     'cr-wave'          { Invoke-CrWave           -Rest $rest }
     'cr-archive'       { Invoke-CrArchive        -Rest $rest }
+    'cr-recall-check'  { Invoke-CrRecallCheck    -Rest $rest }
+    'cr-merge-check'   { Invoke-CrMergeCheck     -Rest $rest }
+    'cr-snapshot'      { Invoke-CrSnapshot       -Rest $rest }
+    'context-version-bump' { Invoke-ContextVersionBump -Rest $rest }
     'context-paths'    { Invoke-ContextPaths     -Rest $rest }
     'model-scaffold'   { Invoke-ModelScaffold    -Rest $rest }
     'version-stamp'    { Invoke-VersionStamp     -Rest $rest }
+    'plan-gate-stamp'  { Invoke-PlanGateStamp    -Rest $rest }
+    'plan-gate-check'  { Invoke-PlanGateCheck    -Rest $rest }
     'checklist-read'   { Invoke-ChecklistRead    -Rest $rest }
     'checklist-apply'  { Invoke-ChecklistApply   -Rest $rest }
     'detect-project'   { Invoke-DetectProject    -Rest $rest }