aw-spec-cli 0.1.21 → 0.1.22

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

@@ -1946,6 +1946,21 @@ function Get-LabeledVersion {
     }
     if ($vals.Count -gt 0) { return $vals[-1] } else { return $null }
 }
+
+# The ratified NON-NEGOTIABLE principles. A thin wrapper: the scan lives in
+# python/aw-principles.py, which BOTH shells invoke, so the list a gate cites cannot
+# differ between them. Defaults to the two halves specify loads; --file overrides.
+function Invoke-PrinciplesList {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $py = Get-Py
+    if (-not $py) { Write-Error 'principles-list: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-principles.py'
+    if (-not (Test-Path $core)) { Write-Error "principles-list: core not found at $core"; exit 1 }
+    & $py $core list --root $repo @Rest
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
 function Invoke-ConstitutionVerify {
     param([string[]]$Rest)
     $file = ''; $template = ''
@@ -2332,7 +2347,12 @@ function Invoke-DeltaPlanScaffold {
         if ($tpl -and (Test-Path $tpl)) { Copy-Item $tpl $target } else { New-Item -ItemType File -Force -Path $target | Out-Null }
         $created = $true
     }
-    Set-HeaderStamp -Path $target -Name 'Wave' -Value (Get-WaveOf -FeatureDir $fd -CrId $crId -Repo $repo)
+    # The lane plan carries the change's wave so a reader of the plan alone can see where it
+    # sits. It is COPIED from the delta-spec, never decided here — so when the spec has no
+    # readable wave the template's `[N]` is left standing, which is what the merge and recall
+    # fences read as "not ordered yet" and refuse on, with the command that stamps it.
+    $scaffoldWave = Get-WaveOfReadable -FeatureDir $fd -CrId $crId -Repo $repo
+    if ($scaffoldWave) { Set-HeaderStamp -Path $target -Name 'Wave' -Value $scaffoldWave }
     $overrideActive = Test-Path (Join-Path $repo (".appweaver/templates/overrides/" + $tplName + ".md"))
     $templateSource = Resolve-NamedTemplate -Name $tplName -RepoRoot $repo
     $tsOut = if ($templateSource) { $templateSource } else { '' }
@@ -2418,7 +2438,8 @@ function Invoke-TestRun {
         switch ($Rest[$i]) {
             { $_ -in '--feature-dir','-FeatureDir' } { $featureDir = $Rest[++$i] }
             { $_ -in '--scope','-Scope' }            { $scope = $Rest[++$i] }
-            { $_ -in '--also','-Also' }              { $also = $Rest[++$i] }
+            # Repeatable, lists UNION — see the bash twin for why the caller passes two.
+            { $_ -in '--also','-Also' }              { $v = $Rest[++$i]; $also = if ($also) { "$also,$v" } else { $v } }
         }
     }
     $repo = Get-RepoRoot
@@ -2714,16 +2735,33 @@ function Get-CrIdToken {
 }
 
 # One change's wave, read from the documents that carry it: the delta-spec first, then the
-# model delta. Both are stamped together, so either answers; 1 is the floor for a change
-# opened before waves existed. Twin of bash _wave_of.
-function Get-WaveOf {
+# model delta. Both are stamped together, so either answers. EMPTY when neither carries a
+# readable one — `**Wave**: [N]` is the unfilled template line, so "no wave" is a state that
+# happens, and a caller who WRITES the answer somewhere must not write a number nobody
+# derived. A phantom wave is worse than none: the merge and recall fences can see that a
+# wave is missing and say so, but a 1 invented downstream reads to them as fact.
+# Twin of bash _wave_of_readable.
+function Get-WaveOfReadable {
     param([string]$FeatureDir, [string]$CrId, [string]$Repo)
     $ctx = Get-ContextDirForFeature -FeatureDir $FeatureDir -Repo $Repo
     foreach ($f in @((Join-Path $FeatureDir "changes/$CrId/delta-spec.md"), (Join-Path $ctx "domain-model.$CrId.delta.md"))) {
         if (-not (Test-Path $f)) { continue }
         $t = Get-Content $f -Raw -ErrorAction SilentlyContinue
-        if ($t -match '(?m)^\*\*Wave\*\*:\s*(\d+)') { return "$([int]$Matches[1])" }
+        if ($t -match '(?m)^\*\*Wave\*\*:\s*(\d+)') {
+            $w = [int]$Matches[1]
+            if ($w -ge 1) { return "$w" }
+        }
     }
+    return ''
+}
+
+# The same reading with the floor applied, for the readers that must show a number — a
+# listing has a column to fill and 1 is the floor for a change opened before waves existed.
+# Twin of bash _wave_of.
+function Get-WaveOf {
+    param([string]$FeatureDir, [string]$CrId, [string]$Repo)
+    $w = Get-WaveOfReadable -FeatureDir $FeatureDir -CrId $CrId -Repo $Repo
+    if ($w) { return $w }
     return '1'
 }
 
@@ -3253,8 +3291,12 @@ required = max([d["wave"] for d in known], default=0) + 1
 current = wave_of(cr)
 ok = current is not None and current >= required
 
+# A change with NO readable wave is stamped too, not only one sitting too low. The merge
+# and recall fences refuse on an unordered change and send the operator here, so the one
+# command they are given has to be able to write the first wave as well as correct a wrong
+# one — a remedy that declines the case it was named for is no remedy.
 stamped = []
-if stamp and current is not None and current < required:
+if stamp and (current is None or current < required):
     line = "**Wave**: %d" % required
     pat = re.compile(r"^\*\*Wave\*\*:.*$", re.M)
     for p in present:
@@ -3265,13 +3307,16 @@ if stamp and current is not None and current < required:
     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:
+if stamped and deps:
     msg = "%s depends on %s, so it was raised to wave %d in %s" % (
         cr, ", ".join("%s (wave %s)" % (d["cr_id"], d["wave"]) for d in known),
         required, ", ".join(stamped))
+elif stamped:
+    msg = "%s declares no predecessor, so it was stamped at wave %d — the floor — in %s" % (
+        cr, required, ", ".join(stamped))
+elif not deps:
+    msg = "%s declares no predecessor, so wave %d is the floor; it carries %s" % (
+        cr, required, current if current is not None else "no wave")
 elif ok:
     msg = "%s is at wave %s, at or above the %d its `## Depends on` requires" % (
         cr, current, required)
@@ -3917,13 +3962,6 @@ function Invoke-CrMergeCheck {
     if (-not $fd) { Write-Error 'cr-merge-check: no feature set and no --feature-dir'; exit 1 }
     $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
 
-    function Get-WaveFile([string]$path) {
-        if (Test-Path -LiteralPath $path) {
-            $m = [regex]::Match((Get-Content -LiteralPath $path -Raw), '(?m)^\*\*Wave\*\*:[ \t]*(\d+)')
-            if ($m.Success) { return [int]$m.Groups[1].Value }
-        }
-        return 1
-    }
     function Format-Ver([string]$v) {
         $v = "$v".Trim()
         if (-not $v) { return '' }
@@ -3931,7 +3969,6 @@ function Invoke-CrMergeCheck {
     }
 
     $mySpec = Join-Path $fd "changes/$crId/delta-spec.md"
-    $wave = Get-WaveFile $mySpec
     $baseVersion = Format-Ver (Get-MdHeader -Path $mySpec -Name 'Base version')
 
     # The master's CURRENT version, from the ledger — the same authority version-read
@@ -3947,63 +3984,59 @@ function Invoke-CrMergeCheck {
     # is absence of evidence and is not treated as a move.
     $rebaseNeeded = [bool]($baseVersion -and $current -and ($baseVersion -ne $current))
 
-    # EVERY open change in the context, both halves. changes/<id>/ under each feature is the
-    # authority for "open"; the pending model deltas are unioned in so a model-only artifact
-    # of a half-built change is still seen.
-    $opens = [ordered]@{}
-    if (Test-Path -LiteralPath $ctx) {
-        foreach ($feat in (Get-ChildItem -LiteralPath $ctx -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
-            $ch = Join-Path $feat.FullName 'changes'
-            if (-not (Test-Path -LiteralPath $ch)) { continue }
-            foreach ($d in (Get-ChildItem -LiteralPath $ch -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
-                if ($d.Name -eq 'archive') { continue }
-                if (-not $opens.Contains($d.Name)) {
-                    $opens[$d.Name] = [ordered]@{ cr_id = $d.Name
-                                                  wave = (Get-WaveFile (Join-Path $d.FullName 'delta-spec.md'))
-                                                  feature = $feat.Name }
-                }
-            }
-        }
-        foreach ($f in (Get-ChildItem -LiteralPath $ctx -File -ErrorAction SilentlyContinue | Sort-Object Name)) {
-            $m = [regex]::Match($f.Name, '^domain-model\.(.+)\.delta\.md$')
-            if (-not $m.Success) { continue }
-            $other = $m.Groups[1].Value
-            if (-not $opens.Contains($other)) {
-                $opens[$other] = [ordered]@{ cr_id = $other; wave = (Get-WaveFile $f.FullName); feature = '' }
-            }
-        }
-    }
-    $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.
-    # 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
+    # BOTH CONTEXT-WIDE QUESTIONS COME FROM aw-crstate, the same module the bash payload
+    # loads, so the two shells cannot answer them differently — which they did while each
+    # carried its own copy of the scan.
+    #
+    # PREDECESSORS. Every open change in the context, both halves: changes/<id>/ under each
+    # feature is the authority for "open", and the pending model deltas are unioned in so a
+    # model-only artifact of a half-built change is still seen. A change whose `**Wave**:`
+    # is unreadable is reported as unordered rather than assumed to be wave 1.
+    #
+    # MERGED-OPEN. The masters can move without the version moving: finalize-delta merges
+    # and close-delta bumps, so between the two spec.md carries a change the number does not
+    # yet reflect, and a second delta sharing the same base_version would compare equal and
+    # merge onto masters that had already shifted under it. A change is MERGED when its id
+    # is the CR cell of a Change History row — in this feature's spec or in the context
+    # model every feature shares, so a SIBLING feature's merged-unclosed change is no longer
+    # invisible. A sibling blocks only where it touched an aggregate this delta also names.
+    #
+    # Fails CLOSED: an unreadable helper reports blocking and nothing ordered.
+    $py = Get-Py
     $crstate = Join-Path $PSScriptRoot '..' 'python' 'aw-crstate.py'
-    if ($pyMerged -and (Test-Path $crstate)) {
+    # `answered` is what says the reader ran, not the shape of what it returned: NO blocking
+    # merged-open change is an empty array, which is exactly what a failed read looks like.
+    $order = $null; $mergedOpen = @(); $mergedText = ''; $answered = $false
+    $why = 'python or aw-crstate.py not found'
+    if ($py -and (Test-Path $crstate)) {
         try {
-            $line = (& $pyMerged $crstate 'merged-open' '--cr' $crId '--feature-dir' $fd '--context-dir' $ctx | Select-Object -First 1)
-            if ($line) { $mergedOpen = @(($line | ConvertFrom-Json).blocking) }
+            $line = (& $py $crstate 'wave-order' '--cr' $crId '--feature-dir' $fd '--context-dir' $ctx '--direction' 'lower' '--scope' 'context' | Select-Object -First 1)
+            if ($line) { $order = ($line | ConvertFrom-Json) }
+            $line = (& $py $crstate 'merged-open' '--cr' $crId '--feature-dir' $fd '--context-dir' $ctx | Select-Object -First 1)
+            if ($line) {
+                $parsed = ($line | ConvertFrom-Json)
+                $mergedOpen = @($parsed.blocking); $mergedText = "$($parsed.blocking_text)"; $answered = $true
+            }
         } catch {
-            $mergedOpen = @([pscustomobject]@{ cr_id = '(merged-open check failed)'; blocking = $true })
+            $order = $null; $answered = $false; $why = "$_"
         }
-    } else {
-        $mergedOpen = @([pscustomobject]@{ cr_id = '(merged-open check unavailable)'; blocking = $true })
     }
+    if (-not $order) {
+        $order = [pscustomobject]@{ wave = $null; wave_known = $false; related = @(); related_count = 0
+                                    related_ids = ''; unknown = @(); unknown_count = 0; unknown_ids = ''
+                                    unknown_blocks = $true; wave_ordering_ok = $false
+                                    wave_problem = "the wave reader could not be run ($why), so no open change in this context is ordered against $crId at all" }
+    }
+    if (-not $answered) {
+        $mergedOpen = @([pscustomobject]@{ cr_id = "(merged-open check failed: $why)"; blocking = $true })
+        $mergedText = $mergedOpen[0].cr_id
+    }
+    $blockers = @($order.related)
 
     Write-Json ([ordered]@{
-        ok = $true; cr_id = $crId; wave = $wave
+        ok = $true; cr_id = $crId
+        wave = $(if ($null -ne $order.wave) { $order.wave } else { '' })
+        wave_known = [bool]$order.wave_known
         exists = (Test-Path -LiteralPath (Join-Path $fd "changes/$crId"))
         # REBASE half — the masters moved because a change CLOSED and bumped the number.
         base_version = $baseVersion; current_version = $current
@@ -4011,14 +4044,19 @@ function Invoke-CrMergeCheck {
         base_stamped = [bool]$baseVersion
         blockers = @($blockers); blocker_count = @($blockers).Count
         has_blockers = (@($blockers).Count -gt 0)
-        blocker_ids = (@($blockers | ForEach-Object { '{0} (wave {1})' -f $_.cr_id, $_.wave }) -join ', ')
+        blocker_ids = $order.related_ids
+        # The changes this one cannot be ordered against at all, in either direction.
+        unordered = @($order.unknown); unordered_count = $order.unknown_count
+        unordered_ids = $order.unknown_ids
+        wave_ordering_ok = [bool]$order.wave_ordering_ok
+        wave_problem = $order.wave_problem
         # The other way the masters move: a change MERGED and has not closed yet.
         merged_open = @($mergedOpen); merged_open_count = @($mergedOpen).Count
         has_merged_open = (@($mergedOpen).Count -gt 0)
-        merged_open_ids = (@($mergedOpen | ForEach-Object { $_.cr_id }) -join ', ')
-        # All three refusals as ONE positive flag, because the engine takes no compound
-        # condition and a gate reading three booleans would need three passes over one question.
-        merge_ok = ((-not $rebaseNeeded) -and (@($blockers).Count -eq 0) -and (@($mergedOpen).Count -eq 0))
+        merged_open_ids = $mergedText
+        # All four refusals as ONE positive flag, because the engine takes no compound
+        # condition and a gate reading four booleans would need four passes over one question.
+        merge_ok = ((-not $rebaseNeeded) -and [bool]$order.wave_ordering_ok -and (@($blockers).Count -eq 0) -and (@($mergedOpen).Count -eq 0))
     })
 }
 
@@ -4039,53 +4077,57 @@ function Invoke-CrRecallCheck {
     $changes = Join-Path $fd 'changes'
     $crDir   = Join-Path $changes $crId
 
-    function Get-WaveOf([string]$dir) {
-        $p = Join-Path $dir 'delta-spec.md'
-        if (Test-Path $p) {
-            $m = [regex]::Match((Get-Content $p -Raw), '(?m)^\*\*Wave\*\*:[ \t]*(\d+)')
-            if ($m.Success) { return [int]$m.Groups[1].Value }
-        }
-        return 1
-    }
-
     # MERGED = a Change History row whose CR cell IS this change, in this feature's spec or
     # in the shared context model — aw-crstate owns that test for all three readers of it.
     # Fails CLOSED: an unreadable helper reports merged, never "never merged", which is the
     # answer that would let close-delta archive a change nobody merged.
+    #
+    # DEPENDANTS come from the same module the merge fence reads in the opposite direction.
+    # An unreadable `**Wave**:` is not wave 1 here either: it used to mean the change was
+    # not counted as higher, so recall withdrew the ground from under a dependant it could
+    # not see. Waves have no ceiling, so any unordered change could sit above this one.
     $spec = Join-Path $fd 'spec.md'
     $merged = $true; $evidence = '(merged check unavailable — treated as merged)'
-    $pyMerged = Get-Py
+    $py = Get-Py
     $crstate = Join-Path $PSScriptRoot '..' 'python' 'aw-crstate.py'
-    if ($pyMerged -and (Test-Path $crstate)) {
+    $order = $null; $why = 'python or aw-crstate.py not found'
+    if ($py -and (Test-Path $crstate)) {
         try {
-            $line = (& $pyMerged $crstate 'merged' '--cr' $crId '--doc' $spec '--doc' (Join-Path $ctx 'domain-model.md') | Select-Object -First 1)
+            $line = (& $py $crstate 'merged' '--cr' $crId '--doc' $spec '--doc' (Join-Path $ctx 'domain-model.md') | Select-Object -First 1)
             if ($line) {
                 $h = $line | ConvertFrom-Json
                 $merged = [bool]$h.merged; $evidence = [string]$h.evidence
             }
-        } catch { }
+            $line = (& $py $crstate 'wave-order' '--cr' $crId '--feature-dir' $fd '--context-dir' $ctx '--direction' 'higher' '--scope' 'feature' | Select-Object -First 1)
+            if ($line) { $order = ($line | ConvertFrom-Json) }
+        } catch { $order = $null; $why = "$_" }
     }
-
-    $wave = if (Test-Path $crDir) { Get-WaveOf $crDir } else { 1 }
-    $dependants = @()
-    if (Test-Path $changes) {
-        foreach ($d in (Get-ChildItem -LiteralPath $changes -Directory | Sort-Object Name)) {
-            if ($d.Name -eq $crId -or $d.Name -eq 'archive') { continue }
-            $w = Get-WaveOf $d.FullName
-            if ($w -gt $wave) { $dependants += [ordered]@{ cr_id = $d.Name; wave = $w } }
-        }
+    if (-not $order) {
+        $order = [pscustomobject]@{ wave = $null; wave_known = $false; related = @(); related_count = 0
+                                    related_ids = ''; unknown = @(); unknown_count = 0; unknown_ids = ''
+                                    unknown_blocks = $true; wave_ordering_ok = $false
+                                    wave_problem = "the wave reader could not be run ($why), so no open change in this feature is ordered against $crId at all" }
     }
+    $dependants = @($order.related)
+
     Write-Json ([ordered]@{
-        ok              = $true
-        cr_id           = $crId
-        exists          = (Test-Path $crDir)
-        wave            = $wave
-        merged          = $merged
-        merge_evidence  = $evidence
-        dependants      = @($dependants)
-        dependant_ids   = (@($dependants | ForEach-Object { '{0} (wave {1})' -f $_.cr_id, $_.wave }) -join ', ')
-        dependant_count = @($dependants).Count
-        has_dependants  = (@($dependants).Count -gt 0)
+        ok               = $true
+        cr_id            = $crId
+        exists           = (Test-Path $crDir)
+        wave             = $(if ($null -ne $order.wave) { $order.wave } else { '' })
+        wave_known       = [bool]$order.wave_known
+        merged           = $merged
+        merge_evidence   = $evidence
+        dependants       = @($dependants)
+        dependant_ids    = $order.related_ids
+        dependant_count  = @($dependants).Count
+        has_dependants   = (@($dependants).Count -gt 0)
+        # The changes this one cannot be ordered against at all, in either direction.
+        unordered        = @($order.unknown)
+        unordered_count  = $order.unknown_count
+        unordered_ids    = $order.unknown_ids
+        wave_ordering_ok = [bool]$order.wave_ordering_ok
+        wave_problem     = $order.wave_problem
     })
 }
 
@@ -4174,71 +4216,26 @@ function Get-FileSha {
     return (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLower()
 }
 
+# THE RULE ITSELF LIVES IN python/aw-plangate.py, which both shells invoke. It was a set
+# of sha comparisons written twice — a heredoc in bash, this function natively — and every
+# change to it had to be re-derived here by hand and kept in step by eye. It changed twice
+# that way. These two are now thin wrappers: resolve the feature, hand over.
 function Invoke-PlanGateStamp {
     param([string[]]$Rest)
-    $fdArg = ''; $specVersion = ''; $mode = 'master'; $verdict = 'conformant'; $planGaps = '0'; $routedRaw = '[]'
+    $fdArg = ''; $pass = @()
     for ($i = 0; $i -lt $Rest.Count; $i++) {
-        switch ($Rest[$i]) {
-            { $_ -in '--feature-dir','-FeatureDir' }   { $fdArg = $Rest[++$i] }
-            { $_ -in '--spec-version','-SpecVersion' } { $specVersion = $Rest[++$i] }
-            { $_ -in '--mode','-Mode' }                { $mode = $Rest[++$i] }
-            { $_ -in '--verdict','-Verdict' }          { $verdict = $Rest[++$i] }
-            { $_ -in '--plan-gaps','-PlanGaps' }       { $planGaps = $Rest[++$i] }
-            { $_ -in '--routed','-Routed' }            { $routedRaw = $Rest[++$i] }
-        }
+        if ($Rest[$i] -in '--feature-dir','-FeatureDir') { $fdArg = $Rest[++$i] }
+        else { $pass += $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
-    # 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()
-        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 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'
-    (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; verdict = $verdict; plan_gaps = $planGapCount
-        routed_gaps = $routed.Count; hashed = @($plans.Keys | Sort-Object)
-        count = $plans.Count; ok = $true
-    })
+    $py = Get-Py
+    if (-not $py) { Write-Error 'plan-gate-stamp: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-plangate.py'
+    if (-not (Test-Path $core)) { Write-Error "plan-gate-stamp: core not found at $core"; exit 1 }
+    & $py $core stamp --feature-dir $fd --context-dir $ctx --root $repo @pass
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 }
 
 function Invoke-PlanGateCheck {
@@ -4250,70 +4247,29 @@ function Invoke-PlanGateCheck {
     $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
     if (-not $fd) { Write-Error 'plan-gate-check: no feature set and no --feature-dir'; exit 1 }
     $ctx = Get-ContextDirForFeature -FeatureDir $fd -Repo $repo
-    $p = Join-Path $fd '.aw-plan-gate.json'
-    $rec = $null
-    if (Test-Path -LiteralPath $p -PathType Leaf) {
-        try { $rec = Get-Content -LiteralPath $p -Raw | ConvertFrom-Json } catch { $rec = $null }
-    }
-    $out = [ordered]@{
-        file = (ConvertTo-RepoRelative -Path $p -RepoRoot $repo); tracked = [bool]$rec
-        gate_fresh = $false; 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 been through analyze-plan in master mode since the gate began leaving a receipt'
-    } else {
-        # 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
-        # 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))
-        # 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 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
+    $py = Get-Py
+    if (-not $py) { Write-Error 'plan-gate-check: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-plangate.py'
+    if (-not (Test-Path $core)) { Write-Error "plan-gate-check: core not found at $core"; exit 1 }
+    & $py $core check --feature-dir $fd --context-dir $ctx --root $repo
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 }
 
 # Which of a lane plan's elements the generated code realises. One implementation
 # (python/aw-plan-coverage.py), called identically by both shells — see the bash twin.
+# Split a gate's findings by the command that closes each one. Twin of the bash
+# cmd_gap_route, calling the SAME aw-gaps.py — see the bash comment for why a plan
+# defect must never be routed to `implement`.
+function Invoke-GapRoute {
+    param([string[]]$Rest)
+    $py = Get-Py
+    if (-not $py) { Write-Error 'gap-route: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-gaps.py'
+    if (-not (Test-Path $core)) { Write-Error "gap-route: core not found at $core"; exit 1 }
+    & $py $core route @Rest
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
 function Invoke-PlanCoverage {
     param([string[]]$Rest)
     $py = Get-Py
@@ -4468,6 +4424,7 @@ switch ($sub) {
     'plan-gate-stamp'  { Invoke-PlanGateStamp    -Rest $rest }
     'plan-gate-check'  { Invoke-PlanGateCheck    -Rest $rest }
     'plan-coverage'    { Invoke-PlanCoverage     -Rest $rest }
+    'gap-route'        { Invoke-GapRoute         -Rest $rest }
     'checklist-read'   { Invoke-ChecklistRead    -Rest $rest }
     'checklist-apply'  { Invoke-ChecklistApply   -Rest $rest }
     'detect-project'   { Invoke-DetectProject    -Rest $rest }
@@ -4483,6 +4440,7 @@ switch ($sub) {
     'setup-constitution' { Invoke-SetupConstitution -Rest $rest }
     'compose-constitution' { Invoke-ComposeConstitution -Rest $rest }
     'constitution-verify' { Invoke-ConstitutionVerify -Rest $rest }
+    'principles-list'     { Invoke-PrinciplesList     -Rest $rest }
     'agent-context-update' { Invoke-AgentContextUpdate -Rest $rest }
     default            { Write-Error "Unknown subcommand: $sub"; exit 1 }
 }

package/assets/.appweaver/scripts/powershell/aw-xref.ps1

@@ -8,7 +8,10 @@
 #   aw-xref.ps1 list           --aggregate Y [--root DIR] [--bundle knowledge]
 #   aw-xref.ps1 concept-upsert   --aggregate X [--source-files a,b,c] [--description D] [--origin ...] [--root DIR]
 #   aw-xref.ps1 concept-overview --aggregate X (--text PROSE | --text-file F) [--root DIR]
-#   aw-xref.ps1 concept-paths    --aggregate X | --feature-dir <dir> [--root DIR] [--bundle knowledge]
+#   aw-xref.ps1 concept-paths    --aggregate X | --feature-dir <dir> [--under <subtree>]...
+#                                [--root DIR] [--bundle knowledge]
+#                                (--under keeps only paths inside that subtree, so a caller
+#                                generating ONE lane is not handed another lane's files)
 #   aw-xref.ps1 feature-aggregates --feature-dir <dir> [--root DIR]
 #                                (the aggregate(s) a feature acts on: its spec's Acts-on line,
 #                                then the boundary map, then the feature name itself)