aw-spec-cli 0.1.32 → 0.1.34

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

@@ -110,23 +110,32 @@ function Invoke-ResolveDomain {
     $rulemap = Join-Path $repo "guardrails/$domain/domain-rule-bindings.md"
     $rulemapExists = ($domain -ne '') -and (Test-Path $rulemap)
 
-    $candidates = @()
+    # A mapped file that is not on disk goes to `missing`, never to `candidates`, so a
+    # caller can say so instead of loading nothing in its place without a word.
+    # heading_found tells a heading that is deliberately empty (a `_None_` line) apart
+    # from one that is absent or misspelled — both give no candidates.
+    $candidates = @(); $missing = @(); $headingFound = $false
     if ($rulemapExists) {
         $lines = Get-Content $rulemap
         $heading = "## /$commandName"
         $grab = $false; $found = @()
         foreach ($line in $lines) {
-            if ($line -eq $heading) { $grab = $true; continue }
+            if ($line -eq $heading) { $grab = $true; $headingFound = $true; continue }
             if ($line -match '^## ') { $grab = $false }
-            if ($grab -and $line -match '^\s*-\s+(.+?)\s*$') { $found += $Matches[1] }
+            # A path written as code (- `path`) is read without its backticks.
+            if ($grab -and $line -match '^\s*-\s+(.+?)\s*$') { $found += ($Matches[1] -replace '^`([^`]+)`$', '$1') }
+        }
+        foreach ($f in $found) {
+            if (Test-Path -LiteralPath (Join-Path $repo $f) -PathType Leaf) { $candidates += $f } else { $missing += $f }
         }
-        if ($found.Count -gt 0) { $candidates = $found }
     }
 
     Write-Json ([ordered]@{
         domain         = $domain
         rulemap_exists = $rulemapExists
+        heading_found  = $headingFound
         candidates     = @($candidates)
+        missing        = @($missing)
     })
 }
 
@@ -175,21 +184,27 @@ function Invoke-ResolveTech {
     $subs['stack'] = $subs['backend_stack']     # the unqualified form means the service lane
     $declared = @($subs.Values | Where-Object { $_ } | Select-Object -Unique)
 
-    $bullets = @()
+    # Whether the command's heading is in the map at all. A heading with no bullets (a
+    # `_None_` line) is a deliberate choice; an absent or misspelled one loads the same
+    # nothing, and only this tells the caller which of the two it is.
+    $bullets = @(); $headingFound = $false
     if ($techmapExists) {
         $lines = Get-Content $techmap
         foreach ($heading in @("## /$commandName", "## /$($commandName -replace 'decl-','')")) {
             $grab = $false; $found = @()
             foreach ($line in $lines) {
-                if ($line -eq $heading) { $grab = $true; continue }
+                if ($line -eq $heading) { $grab = $true; $headingFound = $true; continue }
                 if ($line -match '^## ') { $grab = $false }
-                if ($grab -and $line -match '^\s*-\s+(.+?)\s*$') { $found += $Matches[1] }
+                # A path written as code (- `path`) is read without its backticks.
+                if ($grab -and $line -match '^\s*-\s+(.+?)\s*$') { $found += ($Matches[1] -replace '^`([^`]+)`$', '$1') }
             }
             if ($found.Count -gt 0) { $bullets = $found; break }
         }
     }
 
-    $candidates = @(); $missing = @(); $skipped = @(); $mismatched = @()
+    # A placeholder the kit does not know is a typo in the map, unlike one for a lane
+    # this repo does not declare, which is skipped because its rules do not apply.
+    $candidates = @(); $missing = @(); $skipped = @(); $mismatched = @(); $unknown = @()
     foreach ($b in $bullets) {
         $holes = @([regex]::Matches($b, '\{\{\s*([a-z_]+)\s*\}\}') | ForEach-Object { $_.Groups[1].Value })
         $why = ''
@@ -199,7 +214,11 @@ function Invoke-ResolveTech {
             # genuinely does not exist, so its rules genuinely do not apply.
             if (-not $subs[$h]) { $why = "no lane declared for {{$h}}"; break }
         }
-        if ($why) { $skipped += [ordered]@{ bullet = $b; why = $why }; continue }
+        if ($why) {
+            $skipped += [ordered]@{ bullet = $b; why = $why }
+            if ($why -like 'unknown placeholder*') { $unknown += $b }
+            continue
+        }
         $path = [regex]::Replace($b, '\{\{\s*([a-z_]+)\s*\}\}', { param($m) $subs[$m.Groups[1].Value] })
         if (Test-Path (Join-Path $repo $path)) { $candidates += $path } else { $missing += $path }
         # A LITERAL stack directory that is not one this repo declares. Reported, never
@@ -212,13 +231,30 @@ function Invoke-ResolveTech {
         }
     }
 
+    # A STACK WITH NO RULE FOLDER AT ALL — reported as the folder, see the bash twin. A file
+    # missing from a folder that does exist stays listed in missing_elsewhere.
+    $absent = @(); $absentFiles = 0; $elsewhere = @()
+    foreach ($p in $missing) {
+        $m3 = [regex]::Match($p, '^(guardrails/technology/[^/]+/)')
+        if ($m3.Success -and -not (Test-Path -LiteralPath (Join-Path $repo $m3.Groups[1].Value) -PathType Container)) {
+            if ($absent -notcontains $m3.Groups[1].Value) { $absent += $m3.Groups[1].Value }
+            $absentFiles++
+        } else { $elsewhere += $p }
+    }
+
     Write-Json ([ordered]@{
-        domain             = $domain
-        techrulemap_exists = $techmapExists
-        candidates         = @($candidates)
-        missing            = @($missing)
-        skipped            = @($skipped)
-        declared_stacks    = @($declared | Sort-Object)
+        domain               = $domain
+        techrulemap_exists   = $techmapExists
+        heading_found        = $headingFound
+        candidates           = @($candidates)
+        missing              = @($missing)
+        missing_elsewhere    = @($elsewhere)
+        absent_corpora       = @($absent)
+        absent_corpora_text  = ($absent -join ' and ')
+        absent_files         = $absentFiles
+        skipped              = @($skipped)
+        unknown_placeholders = @($unknown)
+        declared_stacks      = @($declared | Sort-Object)
         stack_mismatch     = ($mismatched.Count -gt 0)
         mismatched_stacks  = @($mismatched)
     })
@@ -579,6 +615,16 @@ function Invoke-AwStackCore {
     if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 }
 
+# One aw-stack call whose JSON the caller reads instead of printing; $null when it fails.
+function Get-AwStackJson {
+    param([string]$Op, [string[]]$Rest)
+    $py = Get-Py
+    if (-not $py) { return $null }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-stack.py'
+    try { return ((& $py $core '--repo' (Get-RepoRoot) $Op @Rest) | Out-String | ConvertFrom-Json) }
+    catch { return $null }
+}
+
 function Invoke-StackList {
     param([string[]]$Rest)
     $fwd = @()
@@ -608,6 +654,20 @@ function Invoke-StackDetect {
     Invoke-AwStackCore -Op 'detect' -Rest $fwd
 }
 
+# Which stacks the active project's technical map has rule files for — see the bash twin.
+function Invoke-StackRules {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--kind'     { $fwd += '--kind'; $fwd += $Rest[++$i] }
+            '--declared' { $fwd += '--declared' }
+            default { Write-Error "stack-rules: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'rules' -Rest $fwd
+}
+
 function Invoke-LaneDeclare {
     param([string[]]$Rest)
     $fwd = @()
@@ -640,8 +700,8 @@ function Invoke-LaneResolve {
     Invoke-AwStackCore -Op 'resolve' -Rest $fwd
 }
 
-# Change the API-contract keys (contract_run, contract, client) on a lane already
-# declared. Twin of bash cmd_lane_set.
+# Change the API-contract keys (contract_write, contract_run, contract, client) on a lane
+# already declared. Twin of bash cmd_lane_set.
 function Invoke-LaneSet {
     param([string[]]$Rest)
     $fwd = @()
@@ -654,8 +714,9 @@ function Invoke-LaneSet {
     Invoke-AwStackCore -Op 'set' -Rest $fwd
 }
 
-# ─────────────── contract-export / -draft / -combine / -requests / -client / -check ───────────────
-# Twins of the bash cmd_contract_export / _draft / _combine / _requests / _client / _check.
+# ─────── contract-export / -draft / -combine / -requests / -client / -check / -verify / -merge, api-split ───────
+# Twins of the bash cmd_contract_export / _draft / _combine / _requests / _client / _check /
+# _verify / _merge and cmd_api_split.
 function Invoke-ContractExport {
     param([string[]]$Rest)
     $fwd = @()
@@ -668,12 +729,19 @@ function Invoke-ContractExport {
     Invoke-AwStackCore -Op 'contract-export' -Rest $fwd
 }
 
+# Each value is forwarded only when it is not empty — PowerShell 5.1 drops an empty
+# argument, and the flag would then take the next one.
 function Invoke-ContractDraft {
     param([string[]]$Rest)
     $fwd = @()
     for ($i = 0; $i -lt $Rest.Count; $i++) {
         switch ($Rest[$i]) {
-            '--feature-dir' { $v = $Rest[++$i]; if ($v) { $fwd += '--feature-dir'; $fwd += $v } }
+            { $_ -in '--feature-dir','--cr' } {
+                $flag = $Rest[$i]
+                if ($i + 1 -lt $Rest.Count -and -not "$($Rest[$i + 1])".StartsWith('--')) {
+                    $v = $Rest[++$i]; if ($v) { $fwd += $flag; $fwd += $v }
+                }
+            }
             default { Write-Error "contract-draft: unknown arg '$($Rest[$i])'"; exit 1 }
         }
     }
@@ -744,6 +812,67 @@ function Invoke-ContractImpact {
     Invoke-AwStackCore -Op 'contract-impact' -Rest $fwd
 }
 
+# cmd_contract_verify: does the built service serve what its plan names; with --check, only
+# whether the plan names anything to check. Each value is forwarded only when it is not
+# empty, as above.
+function Invoke-ContractVerify {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--feature-dir','--cr','--doc' } {
+                $flag = $Rest[$i]
+                if ($i + 1 -lt $Rest.Count -and -not "$($Rest[$i + 1])".StartsWith('--')) {
+                    $v = $Rest[++$i]; if ($v) { $fwd += $flag; $fwd += $v }
+                }
+            }
+            '--check' { $fwd += '--check' }
+            default { Write-Error "contract-verify: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'contract-verify' -Rest $fwd
+}
+
+# cmd_contract_merge: a change's delta API plan, merged into its feature's API plan; with
+# --check, only whether it is still to merge (close-delta).
+function Invoke-ContractMerge {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--feature-dir','--cr' } {
+                $flag = $Rest[$i]
+                if ($i + 1 -lt $Rest.Count -and -not "$($Rest[$i + 1])".StartsWith('--')) {
+                    $v = $Rest[++$i]; if ($v) { $fwd += $flag; $fwd += $v }
+                }
+            }
+            '--check' { $fwd += '--check' }
+            default { Write-Error "contract-merge: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'contract-merge' -Rest $fwd
+}
+
+# cmd_api_split: a feature's endpoints and requests table, moved out of its backend plan
+# into an API plan; --check only reports whether one is still to move.
+function Invoke-ApiSplit {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--feature-dir','--cr' } {
+                $flag = $Rest[$i]
+                if ($i + 1 -lt $Rest.Count -and -not "$($Rest[$i + 1])".StartsWith('--')) {
+                    $v = $Rest[++$i]; if ($v) { $fwd += $flag; $fwd += $v }
+                }
+            }
+            '--check' { $fwd += '--check' }
+            default { Write-Error "api-split: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'api-split' -Rest $fwd
+}
+
 # The gate: is the declaration USABLE for the phase about to run. Twin of bash
 # cmd_lane_verify. --require names a lane kind the phase cannot run without;
 # --allow-missing-root is the greenfield state, where a lane root folder is declared
@@ -1493,6 +1622,10 @@ function Invoke-FeaturePaths {
     $uiDesign = Join-Path $fd 'frontend-plan.md'
     if (-not (Test-Path $design)   -and (Test-Path (Join-Path $fd 'design.md')))    { $design   = Join-Path $fd 'design.md' }
     if (-not (Test-Path $uiDesign) -and (Test-Path (Join-Path $fd 'design.ui.md'))) { $uiDesign = Join-Path $fd 'design.ui.md' }
+    # The API plan beside the backend plan: the service's published endpoints, a master that
+    # finalize-delta merges each change's API into. A feature planned before it existed has
+    # none, and keeps its endpoints in its backend plan until `api-split` moves them.
+    $apiPlan = Join-Path $fd 'api-plan.md'
     # needs_bootstrap, not spec_exists, is what picks specify's branch. A crashed first run
     # leaves spec.md on disk with the marker still up, and branching on the file alone read
     # that as a spec to EXTEND — re-applying the same input over an unfinished v1.0.
@@ -1511,6 +1644,8 @@ function Invoke-FeaturePaths {
         frontend_plan       = $uiDesign
         backend_plan_exists = (Test-Path $design)
         frontend_plan_exists = (Test-Path $uiDesign)
+        api_plan          = $apiPlan
+        api_plan_exists   = (Test-Path $apiPlan)
         design_file       = $design
         ui_design_file    = $uiDesign
         spec_exists       = $specExists
@@ -2602,14 +2737,17 @@ function Invoke-DesignScaffold {
     # backend / frontend are the PLAN-phase pairs: the same templates, the plan document
     # names, and a MIGRATION — a legacy design.md / design.ui.md is RENAMED into the plan
     # name, so a feature never carries two spellings of one master. service / ui stay
-    # byte-identical for the callers that still write the legacy names.
+    # byte-identical for the callers that still write the legacy names. api is the backend
+    # lane's API plan, beside its plan — one template for every project, since its endpoint
+    # block form is fixed.
     $legacyName = ''
     switch ($lane) {
         'service'  { $docName = 'design.md';        if (-not $tplName) { $tplName = 'design-template' } }
         'ui'       { $docName = 'design.ui.md';     if (-not $tplName) { $tplName = 'ui-design-template' } }
         'backend'  { $docName = 'backend-plan.md';  $legacyName = 'design.md';    if (-not $tplName) { $tplName = 'design-template' } }
         'frontend' { $docName = 'frontend-plan.md'; $legacyName = 'design.ui.md'; if (-not $tplName) { $tplName = 'ui-design-template' } }
-        default    { Write-Error ("design-scaffold: unknown --lane '" + $lane + "' (backend|frontend|service|ui)"); exit 1 }
+        'api'      { $docName = 'api-plan.md';      if (-not $tplName) { $tplName = 'api-plan-template' } }
+        default    { Write-Error ("design-scaffold: unknown --lane '" + $lane + "' (backend|frontend|api|service|ui)"); exit 1 }
     }
     $repo = Get-RepoRoot
     $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
@@ -2623,7 +2761,15 @@ function Invoke-DesignScaffold {
     if ((-not (Test-Path $target)) -and $legacyName -and (Test-Path (Join-Path $fd $legacyName))) {
         Move-Item (Join-Path $fd $legacyName) $target; $migrated = $true
     }
-    if (Test-Path $target) { $created = $false }
+    # An API plan is never scaffolded beside a backend plan that still carries the API: the
+    # empty template would be read in its place and the draft would lose every endpoint.
+    # `api-split` moves them first.
+    $blocked = $false
+    if ($lane -eq 'api' -and -not (Test-Path $target)) {
+        $chk = Get-AwStackJson -Op 'api-split' -Rest @('--feature-dir', $fd, '--check')
+        $blocked = [bool]($chk -and $chk.needed)
+    }
+    if ((Test-Path $target) -or $blocked) { $created = $false }
     else {
         $tpl = Resolve-NamedTemplate -Name $tplName -RepoRoot $repo
         if ($tpl -and (Test-Path $tpl)) { Copy-Item $tpl $target } else { New-Item -ItemType File -Force -Path $target | Out-Null }
@@ -2636,7 +2782,7 @@ function Invoke-DesignScaffold {
     $overrideActive = Test-Path (Join-Path $repo (".appweaver/templates/overrides/" + $tplName + ".md"))
     $templateSource = Resolve-NamedTemplate -Name $tplName -RepoRoot $repo
     $tsOut = if ($templateSource) { $templateSource } else { '' }
-    Write-Json ([ordered]@{ feature_dir = $fd; design_doc = $target; plan_doc = $target; lane = $lane; created = $created; migrated = $migrated; override_active = $overrideActive; template = $tplName; template_source = $tsOut })
+    Write-Json ([ordered]@{ feature_dir = $fd; design_doc = $target; plan_doc = $target; lane = $lane; created = $created; migrated = $migrated; blocked = $blocked; override_active = $overrideActive; template = $tplName; template_source = $tsOut })
 }
 
 # ─────────────────────────── delta-plan-scaffold ───────────────────────────
@@ -2665,7 +2811,9 @@ function Invoke-DeltaPlanScaffold {
                      if (-not $tplName) { $tplName = 'delta-design-template' } }
         'frontend' { $docName = 'delta-frontend-plan.md'; $legacyName = 'delta-design.ui.md'
                      if (-not $tplName) { $tplName = 'ui-delta-design-template' } }
-        default    { Write-Error ("delta-plan-scaffold: unknown --lane '" + $lane + "' (backend|frontend)"); exit 1 }
+        'api'      { $docName = 'delta-api-plan.md'; $legacyName = ''
+                     if (-not $tplName) { $tplName = 'delta-api-plan-template' } }
+        default    { Write-Error ("delta-plan-scaffold: unknown --lane '" + $lane + "' (backend|frontend|api)"); exit 1 }
     }
     $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
     if (-not $fd) { Write-Error 'delta-plan-scaffold: no feature set and no --feature-dir'; exit 1 }
@@ -2673,10 +2821,17 @@ function Invoke-DeltaPlanScaffold {
     if (-not (Test-Path $crDir)) { Write-Error ("delta-plan-scaffold: no such open change '" + $crId + "' (looked in " + $crDir + ")"); exit 1 }
     $target = Join-Path $crDir $docName
     $created = $false; $migrated = $false
-    if ((-not (Test-Path $target)) -and (Test-Path (Join-Path $crDir $legacyName))) {
+    if ((-not (Test-Path $target)) -and $legacyName -and (Test-Path (Join-Path $crDir $legacyName))) {
         Move-Item (Join-Path $crDir $legacyName) $target; $migrated = $true
     }
-    if (-not (Test-Path $target)) {
+    # A change planned before the delta API plan existed keeps its API in its delta backend
+    # plan, which is read in its place; an empty delta API plan beside it would hide it.
+    $blocked = $false
+    if ($lane -eq 'api' -and -not (Test-Path $target)) {
+        $chk = Get-AwStackJson -Op 'api-split' -Rest @('--feature-dir', $fd, '--cr', $crId)
+        $blocked = [bool]($chk -and $chk.needed)
+    }
+    if ((-not (Test-Path $target)) -and -not $blocked) {
         $tpl = Resolve-NamedTemplate -Name $tplName -RepoRoot $repo
         if ($tpl -and (Test-Path $tpl)) { Copy-Item $tpl $target } else { New-Item -ItemType File -Force -Path $target | Out-Null }
         $created = $true
@@ -2686,11 +2841,11 @@ function Invoke-DeltaPlanScaffold {
     # 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 }
+    if ($scaffoldWave -and (Test-Path $target)) { 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 { '' }
-    Write-Json ([ordered]@{ cr_id = $crId; cr_dir = $crDir; lane = $lane; delta_plan = $target; created = $created; migrated = $migrated; override_active = $overrideActive; template = $tplName; template_source = $tsOut })
+    Write-Json ([ordered]@{ cr_id = $crId; cr_dir = $crDir; lane = $lane; delta_plan = $target; created = $created; migrated = $migrated; blocked = $blocked; override_active = $overrideActive; template = $tplName; template_source = $tsOut })
 }
 
 # Read one field out of the lane model. Twin of the bash inline python readers: the
@@ -3204,6 +3359,29 @@ function Invoke-ModelScaffold {
     })
 }
 
+# ──────────────────── model-guard-snapshot / model-guard-check ─────────────────────
+# Bracket a whole-file rewrite of the context's domain-model.md (specify bootstrap, adopt):
+# the snapshot copies the model aside, the check compares the rewrite with the copy and, on
+# a loss, restores the model and keeps the rewrite as domain-model.rejected.md. THE RULE
+# LIVES IN python/aw-model-guard.py, which both shells invoke — see the bash twin. Both
+# exit 0 with `ok` in the JSON; the workflow's gate owns the stop.
+function Invoke-ModelGuard {
+    param([string]$Op, [string[]]$Rest)
+    $model = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        if ($Rest[$i] -in '--model','-Model') { $model = $Rest[++$i] }
+    }
+    if (-not $model) { Write-Error "model-guard-${Op}: --model required"; exit 1 }
+    $repo = Get-RepoRoot
+    if (-not [System.IO.Path]::IsPathRooted($model)) { $model = Join-Path $repo $model }
+    $py = Get-Py
+    if (-not $py) { Write-Error "model-guard-${Op}: python3 is required"; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-model-guard.py'
+    if (-not (Test-Path -LiteralPath $core)) { Write-Error "model-guard-${Op}: core not found at $core"; exit 1 }
+    & $py $core $Op --model $model --root $repo
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
 # ─────────────────────────── cr-list ───────────────────────────────────────
 # The changes currently OPEN on a feature, in wave order. This is what lets a delta stage
 # ASK which change it is working on instead of inferring one: many may be open at once,
@@ -3404,6 +3582,7 @@ function Invoke-CrPaths {
     $dmodel = Join-Path $ctx "domain-model.$crId.delta.md"
     $be     = Join-Path $crDir 'delta-backend-plan.md'
     $fe     = Join-Path $crDir 'delta-frontend-plan.md'
+    $api    = Join-Path $crDir 'delta-api-plan.md'
     $master = Join-Path $ctx 'domain-model.md'
     $wave = [int](Get-WaveOf -FeatureDir $fd -CrId $crId -Repo $repo)
     $recorded = @(Get-ChangeLanes -Path $dspec)
@@ -3445,6 +3624,8 @@ function Invoke-CrPaths {
         delta_model = (ConvertTo-RepoRelative -Path $dmodel -RepoRoot $repo); delta_model_exists = (Test-Path $dmodel)
         delta_backend_plan = (ConvertTo-RepoRelative -Path $be -RepoRoot $repo); delta_backend_plan_exists = (Test-Path $be)
         delta_frontend_plan = (ConvertTo-RepoRelative -Path $fe -RepoRoot $repo); delta_frontend_plan_exists = (Test-Path $fe)
+        # The change's API delta — merged into the feature's api-plan.md by finalize-delta.
+        delta_api_plan = (ConvertTo-RepoRelative -Path $api -RepoRoot $repo); delta_api_plan_exists = (Test-Path $api)
         wave = $wave
         # The lanes this change touches, from its delta-spec's **Lanes** line — every lane
         # when it records none (lanes_recorded false).
@@ -4348,13 +4529,26 @@ function Invoke-CrSnapshot {
     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.
+    # Every document finalize-delta may rewrite: the two masters it merges into, the API plan
+    # it merges the change's API into, the backend plan the first such merge moves the
+    # endpoints out of, and the API draft it redraws.
+    $backend = Join-Path $fd 'backend-plan.md'
+    if (-not (Test-Path -LiteralPath $backend) -and (Test-Path -LiteralPath (Join-Path $fd 'design.md'))) {
+        $backend = Join-Path $fd 'design.md'
+    }
+    $docs = @(@($spec, 'spec.md'), @($model, 'domain-model.md'),
+              @((Join-Path $fd 'api-plan.md'), 'api-plan.md'),
+              @($backend, (Split-Path -Leaf $backend)),
+              @((Join-Path $fd 'api-draft.json'), 'api-draft.json'))
+    # Flat names, not the source tree's shape: the documents 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'))) {
+    $sources = [ordered]@{}
+    foreach ($pair in $docs) {
         if (Test-Path -LiteralPath $pair[0] -PathType Leaf) {
             Copy-Item -LiteralPath $pair[0] -Destination (Join-Path $snap $pair[1]) -Force
             $copied += $pair[1]
+            $sources[$pair[1]] = (ConvertTo-RepoRelative -Path $pair[0] -RepoRoot $repo)
         }
     }
 
@@ -4370,10 +4564,7 @@ function Invoke-CrSnapshot {
         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)
-        }
+        sources         = $sources
         # 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. " +
@@ -4772,6 +4963,31 @@ function Invoke-PlanCoverage {
     if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 }
 
+# Which of a lane plan's requirement ids no test of the slice names. Same core as
+# plan-coverage (python/aw-plan-coverage.py --citations), called identically by both
+# shells — see the bash twin.
+function Invoke-TestCitations {
+    param([string[]]$Rest)
+    $py = Get-Py
+    if (-not $py) { Write-Error 'test-citations: python3 is required'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-plan-coverage.py'
+    if (-not (Test-Path $core)) { Write-Error "test-citations: core not found at $core"; exit 1 }
+    # --flag=value: a lane with no test path or a feature with no model passes an empty
+    # value, and PowerShell 5.1 drops an empty argument.
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        $a = "$($Rest[$i])"
+        if ($a -in '--plan','--kind','--mode','--paths','--source-path','--test-path','--spec','--model','--known-gaps') {
+            $v = ''
+            if ($i + 1 -lt $Rest.Count -and -not "$($Rest[$i + 1])".StartsWith('--')) { $v = $Rest[++$i] }
+            $fwd += ($a + '=' + $v)
+        } else { $fwd += $a }
+    }
+    $repo = Get-RepoRoot
+    & $py $core '--repo' $repo '--citations' @fwd
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
 # Stamp a version into the MASTER documents' `**Version**:` headers — the
 # deterministic twin of cr-archive's active_version.json bump. close-delta calls
 # this with the version cr-archive just computed, so all THREE carriers of the
@@ -4805,8 +5021,9 @@ function Invoke-VersionStamp {
     # spine cannot tolerate. A lane the feature does not have reports `missing` and nothing
     # fails, which is also how the legacy names are carried — a feature not yet migrated to
     # the plan names still gets stamped, and one that has been migrated reports the legacy
-    # pair missing.
-    foreach ($name in @('spec.md', 'backend-plan.md', 'frontend-plan.md', 'design.md', 'design.ui.md')) {
+    # pair missing. The API plan is a master too, and moves with them.
+    foreach ($name in @('spec.md', 'backend-plan.md', 'frontend-plan.md', 'design.md', 'design.ui.md',
+                        'api-plan.md')) {
         $p = Join-Path $fd $name
         if (-not (Test-Path $p)) { $missing += $name; continue }
         $src = Get-Content -Raw -Encoding UTF8 $p
@@ -4823,11 +5040,14 @@ function Invoke-VersionStamp {
     # 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.
+    # belongs to a change that closed, and re-stamping it would rewrite history. The API
+    # plan's row, which finalize-delta's API merge wrote, is completed the same way.
     $rowFilled = $false; $rowWas = ''
+    [string[]]$rowsFilled = @()
     if ($crId) {
-        $p = Join-Path $fd 'spec.md'
-        if (Test-Path -LiteralPath $p) {
+        foreach ($name in @('spec.md', 'api-plan.md')) {
+            $p = Join-Path $fd $name
+            if (-not (Test-Path -LiteralPath $p)) { continue }
             $lines = [System.IO.File]::ReadAllLines($p)
             $changed = $false
             for ($i = 0; $i -lt $lines.Count; $i++) {
@@ -4837,7 +5057,7 @@ function Invoke-VersionStamp {
                     $cells = $line -split '\|'
                     if ($cells.Count -gt 2 -and
                         @('(pending)','pending','—','-','') -contains $cells[1].Trim().ToLower()) {
-                        $rowWas = $cells[1].Trim()
+                        if ($name -eq 'spec.md') { $rowWas = $cells[1].Trim() }
                         $cells[1] = " $ver "
                         $lines[$i] = ($cells -join '|')
                         $changed = $true
@@ -4846,7 +5066,8 @@ function Invoke-VersionStamp {
             }
             if ($changed) {
                 [System.IO.File]::WriteAllLines($p, $lines)
-                $rowFilled = $true
+                $rowsFilled += $name
+                if ($name -eq 'spec.md') { $rowFilled = $true }
             }
         }
     }
@@ -4856,7 +5077,10 @@ function Invoke-VersionStamp {
                             # 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 })
+                            cr_id = $crId; history_row_filled = $rowFilled; history_row_was = $rowWas
+                            # Every document whose pending row was completed: spec.md, and the
+                            # API plan when the change merged an API delta into it.
+                            history_rows_filled = @($rowsFilled) })
 }
 
 # ─────────────────────────────── main ──────────────────────────────────────
@@ -4874,6 +5098,7 @@ switch ($sub) {
     'set-domain'       { Invoke-SetDomain        -Rest $rest }
     'stack-list'       { Invoke-StackList        -Rest $rest }
     'stack-detect'     { Invoke-StackDetect      -Rest $rest }
+    'stack-rules'      { Invoke-StackRules       -Rest $rest }
     'lane-declare'     { Invoke-LaneDeclare      -Rest $rest }
     'lane-resolve'     { Invoke-LaneResolve      -Rest $rest }
     'lane-verify'      { Invoke-LaneVerify       -Rest $rest }
@@ -4887,6 +5112,9 @@ switch ($sub) {
     'contract-client'  { Invoke-ContractClient   -Rest $rest }
     'contract-check'   { Invoke-ContractCheck    -Rest $rest }
     'contract-impact'  { Invoke-ContractImpact   -Rest $rest }
+    'contract-verify'  { Invoke-ContractVerify   -Rest $rest }
+    'contract-merge'   { Invoke-ContractMerge    -Rest $rest }
+    'api-split'        { Invoke-ApiSplit         -Rest $rest }
     'list-contexts'    { Invoke-ListContexts     -Rest $rest }
     'set-context'      { Invoke-SetContext       -Rest $rest }
     'list-features'    { Invoke-ListFeatures     -Rest $rest }
@@ -4923,11 +5151,14 @@ switch ($sub) {
     'context-version-bump' { Invoke-ContextVersionBump -Rest $rest }
     'context-paths'    { Invoke-ContextPaths     -Rest $rest }
     'model-scaffold'   { Invoke-ModelScaffold    -Rest $rest }
+    'model-guard-snapshot' { Invoke-ModelGuard -Op 'snapshot' -Rest $rest }
+    'model-guard-check' { Invoke-ModelGuard -Op 'check' -Rest $rest }
     'version-stamp'    { Invoke-VersionStamp     -Rest $rest }
     'plan-gaps'        { Invoke-PlanGaps         -Rest $rest }
     'plan-gate-stamp'  { Invoke-PlanGateStamp    -Rest $rest }
     'plan-gate-check'  { Invoke-PlanGateCheck    -Rest $rest }
     'plan-coverage'    { Invoke-PlanCoverage     -Rest $rest }
+    'test-citations'   { Invoke-TestCitations    -Rest $rest }
     'gap-route'        { Invoke-GapRoute         -Rest $rest }
     'checklist-read'   { Invoke-ChecklistRead    -Rest $rest }
     'checklist-apply'  { Invoke-ChecklistApply   -Rest $rest }