aw-spec-cli 0.1.8 → 0.1.10

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

@@ -0,0 +1,2232 @@
+#!/usr/bin/env pwsh
+#
+# aw-spec-actions.ps1 — common action dispatcher for the aw-spec orchestrator
+# (Windows / PowerShell mirror of aw-spec-actions.sh).
+#
+# ONE shared script for every integration (.claude / .agents / .kilocode). The
+# orchestrator workflows reach these subcommands through `execute_script` steps.
+# Each subcommand performs deterministic, governance-safe work and prints a single
+# JSON object on stdout. NONE of these actions author spec/code content — content
+# generation is the LLM's job, in the workflow's agent_* steps.
+#
+# Usage: aw-spec-actions.ps1 <subcommand> [options]
+#   resolve-domain   -Command <name>
+#   resolve-tech     -Command <name>
+#   derive-names     <feature description...>
+#   scaffold         -FeatureDir <path> [-AllowExisting]
+#   resolve-hooks    -Phase <before_specify|after_specify>
+#   create-checklist -FeatureDir <path> [-FeatureName <name>]
+
+$ErrorActionPreference = 'Stop'
+
+# ─────────────────────────── shared helpers ────────────────────────────────
+function Get-RepoRoot {
+    $dir = (Get-Location).Path
+    while ($true) {
+        if (Test-Path (Join-Path $dir '.appweaver')) { return $dir }
+        $parent = Split-Path $dir -Parent
+        if ([string]::IsNullOrEmpty($parent) -or $parent -eq $dir) { break }
+        $dir = $parent
+    }
+    return (Resolve-Path (Join-Path $PSScriptRoot '..' '..' '..')).Path
+}
+
+function ConvertTo-RepoRelative {
+    param([string]$Path, [string]$RepoRoot)
+    $prefix = $RepoRoot.TrimEnd([System.IO.Path]::DirectorySeparatorChar) + [System.IO.Path]::DirectorySeparatorChar
+    if ($Path.StartsWith($prefix)) { $Path = $Path.Substring($prefix.Length) }
+    return ($Path -replace '\\', '/')
+}
+
+function Resolve-SpecTemplate {
+    param([string]$RepoRoot)
+    $base = Join-Path $RepoRoot '.appweaver/templates'
+    $name = 'spec-template.md'
+    $override = Join-Path $base "overrides/$name"
+    if (Test-Path $override) { return $override }
+    $presets = Join-Path $RepoRoot '.appweaver/presets'
+    if (Test-Path $presets) {
+        $hit = Get-ChildItem -Directory $presets -ErrorAction SilentlyContinue |
+            ForEach-Object { Join-Path $_.FullName "templates/$name" } |
+            Where-Object { Test-Path $_ } | Select-Object -First 1
+        if ($hit) { return $hit }
+    }
+    $exts = Join-Path $RepoRoot '.appweaver/extensions'
+    if (Test-Path $exts) {
+        $hit = Get-ChildItem -Directory $exts -ErrorAction SilentlyContinue |
+            Where-Object { -not $_.Name.StartsWith('.') } |
+            ForEach-Object { Join-Path $_.FullName "templates/$name" } |
+            Where-Object { Test-Path $_ } | Select-Object -First 1
+        if ($hit) { return $hit }
+    }
+    $core = Join-Path $base $name
+    if (Test-Path $core) { return $core }
+    return $null
+}
+
+function Write-Json { param($Obj) $Obj | ConvertTo-Json -Compress -Depth 6 }
+
+# ─────────────────────────── resolve-domain ────────────────────────────────
+function Invoke-ResolveDomain {
+    param([string[]]$Rest)
+    $commandName = 'aw-spec-specify'
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--command' { $commandName = $Rest[++$i] }
+            '-Command'  { $commandName = $Rest[++$i] }
+        }
+    }
+    $repo = Get-RepoRoot
+    $domainJson = Join-Path $repo '.appweaver/domain.json'
+    $domain = ''
+    if (Test-Path $domainJson) {
+        try { $domain = (Get-Content $domainJson -Raw | ConvertFrom-Json).domain } catch { $domain = '' }
+        if (-not $domain) { $domain = '' }
+    }
+    $rulemap = Join-Path $repo "guardrails/projects/$domain/domain-rule-bindings.md"
+    $rulemapExists = ($domain -ne '') -and (Test-Path $rulemap)
+
+    $candidates = @()
+    if ($rulemapExists) {
+        $lines = Get-Content $rulemap
+        $heading = "## /$commandName"
+        $grab = $false; $found = @()
+        foreach ($line in $lines) {
+            if ($line -eq $heading) { $grab = $true; continue }
+            if ($line -match '^## ') { $grab = $false }
+            if ($grab -and $line -match '^\s*-\s+(.+?)\s*$') { $found += $Matches[1] }
+        }
+        if ($found.Count -gt 0) { $candidates = $found }
+    }
+
+    Write-Json ([ordered]@{
+        domain         = $domain
+        rulemap_exists = $rulemapExists
+        candidates     = @($candidates)
+    })
+}
+
+# ─────────────────────────── resolve-tech ───────────────────────────────────
+# Technical rule-file mapping — parallel to resolve-domain, but reads
+# guardrails/projects/<project>/tech-rule-bindings.md. The TECHNICAL rule files live in the
+# shared per-stack corpora at guardrails/technology/<stack>/ (rules) and
+# guardrails/technology/<stack>/examples/ (the worked sample for a rule file), and are
+# configured per-command in this map, so they can be tuned per project WITHOUT editing the
+# workflows and a second project can map the same corpus. The technical CONSTITUTION
+# (constitution.technical.md) is NOT mapped — it is still referred to directly by
+# each consumer, as-is.
+# A bullet may name its stack with a PLACEHOLDER — {{stack}} / {{backend_stack}} /
+# {{frontend_stack}} / {{backend_ecosystem}} / {{frontend_ecosystem}} — resolved from
+# the lanes in .appweaver/stacks.json. That is what lets one map serve a Spring repo and
+# a .NET repo without an edit. A bullet that instead spells a stack directory out is kept
+# and USED (it may be a deliberate cross-stack reference) but reported through
+# stack_mismatch when it is not a stack this repo declares, because a map pinned to the
+# wrong corpus is how a Java project ends up being handed C# rules.
+function Invoke-ResolveTech {
+    param([string[]]$Rest)
+    $commandName = 'aw-spec-design'
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--command' { $commandName = $Rest[++$i] }
+            '-Command'  { $commandName = $Rest[++$i] }
+        }
+    }
+    $repo = Get-RepoRoot
+    $domainJson = Join-Path $repo '.appweaver/domain.json'
+    $domain = ''
+    if (Test-Path $domainJson) {
+        try { $domain = (Get-Content $domainJson -Raw | ConvertFrom-Json).domain } catch { $domain = '' }
+        if (-not $domain) { $domain = '' }
+    }
+    $techmap = Join-Path $repo "guardrails/projects/$domain/tech-rule-bindings.md"
+    $techmapExists = ($domain -ne '') -and (Test-Path $techmap)
+
+    # The declared stacks, so one map can be written for any of them.
+    $subs = [ordered]@{
+        'backend_stack'      = (Get-LaneField -Field 'backend_profile')
+        'frontend_stack'     = (Get-LaneField -Field 'frontend_profile')
+        'backend_ecosystem'  = (Get-LaneField -Field 'backend_ecosystem')
+        'frontend_ecosystem' = (Get-LaneField -Field 'frontend_ecosystem')
+    }
+    $subs['stack'] = $subs['backend_stack']     # the unqualified form means the service lane
+    $declared = @($subs.Values | Where-Object { $_ } | Select-Object -Unique)
+
+    $bullets = @()
+    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 -match '^## ') { $grab = $false }
+                if ($grab -and $line -match '^\s*-\s+(.+?)\s*$') { $found += $Matches[1] }
+            }
+            if ($found.Count -gt 0) { $bullets = $found; break }
+        }
+    }
+
+    $candidates = @(); $missing = @(); $skipped = @(); $mismatched = @()
+    foreach ($b in $bullets) {
+        $holes = @([regex]::Matches($b, '\{\{\s*([a-z_]+)\s*\}\}') | ForEach-Object { $_.Groups[1].Value })
+        $why = ''
+        foreach ($h in $holes) {
+            if (-not $subs.Contains($h)) { $why = "unknown placeholder {{$h}}"; break }
+            # A frontend placeholder in a backend-only repo is not an error: the lane
+            # 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 }
+        $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
+        # dropped: the file exists and the project chose it, so it may be a deliberate
+        # cross-stack reference — but it is also exactly how a Java repo ends up being
+        # handed C# rules, and that must not be invisible.
+        $m2 = [regex]::Match($path, '^guardrails/technology/([^/]+)/')
+        if ($m2.Success -and $declared.Count -gt 0 -and ($declared -notcontains $m2.Groups[1].Value) -and ($b -notmatch '\{\{')) {
+            if ($mismatched -notcontains $m2.Groups[1].Value) { $mismatched += $m2.Groups[1].Value }
+        }
+    }
+
+    Write-Json ([ordered]@{
+        domain             = $domain
+        techrulemap_exists = $techmapExists
+        candidates         = @($candidates)
+        missing            = @($missing)
+        skipped            = @($skipped)
+        declared_stacks    = @($declared | Sort-Object)
+        stack_mismatch     = ($mismatched.Count -gt 0)
+        mismatched_stacks  = @($mismatched)
+    })
+}
+
+# ─────────────────────────── derive-names ──────────────────────────────────
+function ConvertTo-Pascal {
+    param([string]$In)
+    ($In -replace '-', ' ').Split(' ') | Where-Object { $_ } |
+        ForEach-Object { $_.Substring(0,1).ToUpper() + $_.Substring(1) } | Join-String
+}
+
+function Get-ShortName {
+    param([string]$Description)
+    $stop = 'i','a','an','the','to','for','of','in','on','at','by','with','from','is','are','was','were',
+            'be','been','being','have','has','had','do','does','did','will','would','should','could','can',
+            'may','might','must','shall','this','that','these','those','my','your','our','their','want','need','add','get','set'
+    $clean = ($Description.ToLower() -replace '[^a-z0-9]', ' ')
+    $words = @()
+    foreach ($w in ($clean.Split(' ') | Where-Object { $_ })) {
+        if (($stop -notcontains $w) -and $w.Length -ge 3) { $words += $w }
+    }
+    $max = if ($words.Count -eq 4) { 4 } else { 3 }
+    $result = ($words | Select-Object -First $max) -join '-'
+    if (-not $result) { $result = 'feature' }
+    return $result
+}
+
+
+# ─────────────────────────── scaffold ──────────────────────────────────────
+function Invoke-Scaffold {
+    param([string[]]$Rest)
+    $featureDirArg = ''; $allowExisting = $false
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--feature-dir','-FeatureDir' } { $featureDirArg = $Rest[++$i] }
+            { $_ -in '--allow-existing','-AllowExisting' } { $allowExisting = $true }
+        }
+    }
+    if (-not $featureDirArg) { Write-Error 'scaffold: --feature-dir is required'; exit 1 }
+
+    $repo = Get-RepoRoot
+    $featureDir = if ([System.IO.Path]::IsPathRooted($featureDirArg)) { $featureDirArg } else { Join-Path $repo $featureDirArg }
+    $specFile = Join-Path $featureDir 'spec.md'
+
+    $dirExisted = Test-Path $featureDir
+    if ($dirExisted -and -not $allowExisting) { Write-Error "scaffold: '$featureDir' already exists (use --allow-existing)"; exit 1 }
+    New-Item -ItemType Directory -Force -Path $featureDir | Out-Null
+    $created = -not $dirExisted
+
+    $template = $null; $specCreated = $false
+    if (-not (Test-Path $specFile)) {
+        $template = Resolve-SpecTemplate -RepoRoot $repo
+        if ($template -and (Test-Path $template)) { Copy-Item $template $specFile } else { New-Item -ItemType File -Force -Path $specFile | Out-Null }
+        $specCreated = $true
+    }
+
+    $featureJson = Join-Path $repo '.appweaver/feature.json'
+    New-Item -ItemType Directory -Force -Path (Join-Path $repo '.appweaver') | Out-Null
+    @{ feature_directory = (ConvertTo-RepoRelative -Path $featureDir -RepoRoot $repo) } |
+        ConvertTo-Json -Compress | Set-Content -Path $featureJson -Encoding UTF8
+
+    Write-Json ([ordered]@{
+        feature_dir  = $featureDir
+        spec_file    = $specFile
+        template     = if ($template) { $template } else { '' }
+        created      = $created
+        spec_created = $specCreated
+    })
+}
+
+# ─────────────────────────── resolve-hooks ─────────────────────────────────
+# Native indentation parser for the known extensions.yml shape (no YAML module).
+# Accepts multiple --phase; merges + dedupes by command.
+function Get-HookIndent([string]$s) { return ($s.Length - $s.TrimStart(' ').Length) }
+
+function Get-PhaseHooks {
+    param([string[]]$Lines, [string]$Phase)
+    $hooks = @(); $n = $Lines.Count; $i = 0
+    while ($i -lt $n) {
+        if ($Lines[$i].TrimEnd() -eq 'hooks:') {
+            $base = Get-HookIndent $Lines[$i]; $i++
+            while ($i -lt $n -and ($Lines[$i].Trim() -eq '' -or (Get-HookIndent $Lines[$i]) -gt $base)) {
+                $st0 = $Lines[$i].Trim()
+                if ($st0.TrimEnd(':') -eq $Phase -and $st0.EndsWith(':') -and -not $st0.StartsWith('- ')) {
+                    $phInd = Get-HookIndent $Lines[$i]; $i++
+                    $cur = $null
+                    while ($i -lt $n) {
+                        $l = $Lines[$i]
+                        if ($l.Trim() -eq '') { $i++; continue }
+                        $ind = Get-HookIndent $l; $st = $l.Trim()
+                        if ($ind -lt $phInd) { break }
+                        if ($ind -eq $phInd -and $st.EndsWith(':') -and -not $st.StartsWith('- ')) { break }
+                        if ($st.StartsWith('- ')) {
+                            if ($null -ne $cur) { $hooks += ,$cur }
+                            $cur = @{}; $st = $st.Substring(2)
+                        }
+                        if ($null -ne $cur -and $st.Contains(':') -and -not $st.StartsWith('- ')) {
+                            $k = $st.Substring(0, $st.IndexOf(':')).Trim()
+                            $v = $st.Substring($st.IndexOf(':') + 1).Trim()
+                            $cur[$k] = $v
+                        }
+                        $i++
+                    }
+                    if ($null -ne $cur) { $hooks += ,$cur }
+                    break
+                } else { $i++ }
+            }
+            break
+        }
+        $i++
+    }
+    return ,$hooks
+}
+
+function Invoke-ResolveHooks {
+    param([string[]]$Rest)
+    $phases = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        if ($Rest[$i] -in '--phase','-Phase') { $phases += $Rest[++$i] }
+    }
+    if ($phases.Count -eq 0) { Write-Error 'resolve-hooks: at least one --phase is required'; exit 1 }
+
+    $repo = Get-RepoRoot
+    $ext = Join-Path $repo '.appweaver/extensions.yml'
+    if (-not (Test-Path $ext)) { Write-Json ([ordered]@{ phases = @($phases); hooks = @() }); return }
+    $lines = Get-Content $ext
+
+    $out = @(); $seen = @{}
+    foreach ($phase in $phases) {
+        foreach ($h in (Get-PhaseHooks -Lines $lines -Phase $phase)) {
+            if ("$($h['enabled'])".ToLower() -eq 'false') { continue }
+            $cond = $h['condition']
+            if ($null -ne $cond -and "$cond".Trim().ToLower() -notin @('', 'null', '~')) { continue }
+            $cmd = [string]$h['command']
+            if ($seen.ContainsKey($cmd)) { continue }
+            $seen[$cmd] = $true
+            $out += [ordered]@{
+                extension   = [string]$h['extension']
+                command     = $cmd
+                slash       = if ($cmd) { '/' + ($cmd -replace '\.', '-') } else { '' }
+                optional    = ("$($h['optional'])".ToLower() -eq 'true')
+                description = [string]$h['description']
+                prompt      = [string]$h['prompt']
+            }
+        }
+    }
+    Write-Json ([ordered]@{ phases = @($phases); hooks = @($out) })
+}
+
+# ─────────────────────────── create-checklist ──────────────────────────────
+function Invoke-CreateChecklist {
+    param([string[]]$Rest)
+    $featureDirArg = ''; $featureName = ''; $kind = 'master'; $changeDirArg = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--feature-dir','-FeatureDir' } { $featureDirArg = $Rest[++$i] }
+            { $_ -in '--feature-name','-FeatureName' } { $featureName = $Rest[++$i] }
+            { $_ -in '--kind','-Kind' } { $kind = $Rest[++$i] }
+            { $_ -in '--change-dir','-ChangeDir' } { $changeDirArg = $Rest[++$i] }
+        }
+    }
+    if (-not $featureDirArg) { Write-Error 'create-checklist: --feature-dir is required'; exit 1 }
+    if ($kind -notin 'master','delta') { Write-Error "create-checklist: --kind must be 'master' or 'delta' (got '$kind')"; exit 1 }
+
+    $repo = Get-RepoRoot
+    $featureDir = if ([System.IO.Path]::IsPathRooted($featureDirArg)) { $featureDirArg } else { Join-Path $repo $featureDirArg }
+    if (-not $featureName) { $featureName = Split-Path $featureDir -Leaf }
+
+    # WHERE the checklist lives and WHAT it grades are decided together here, and both
+    # are reported back, so a caller binds the pair from ONE call and can never point a
+    # checklist at the wrong document. master -> the feature's spec.md; delta -> the
+    # change's delta-spec.md (checklist sits beside it, inside changes/<cr-id>/).
+    $crId = ''
+    if ($kind -eq 'delta') {
+        if (-not $changeDirArg) { Write-Error 'create-checklist: --change-dir is required with --kind delta'; exit 1 }
+        $changeDir = if ([System.IO.Path]::IsPathRooted($changeDirArg)) { $changeDirArg } else { Join-Path $repo $changeDirArg }
+        $crId = Split-Path $changeDir -Leaf
+        $checklistDir = Join-Path $changeDir 'checklists'
+        $targetFile = Join-Path $changeDir 'delta-spec.md'
+    } else {
+        $checklistDir = Join-Path $featureDir 'checklists'
+        $targetFile = Join-Path $featureDir 'spec.md'
+    }
+    $checklistFile = Join-Path $checklistDir 'requirements.md'
+    New-Item -ItemType Directory -Force -Path $checklistDir | Out-Null
+    $created = -not (Test-Path $checklistFile)
+    $today = Get-Date -Format 'yyyy-MM-dd'
+
+    $content = if ($kind -eq 'delta') { @"
+# Delta-Spec Quality Checklist: $featureName — $crId
+
+**Purpose**: Validate the CHANGE's delta-spec before proceeding to design
+**Created**: $today
+**Change**: [delta-spec.md](../delta-spec.md)
+
+## Content Quality
+
+- [ ] No implementation mechanics (languages, frameworks, code/adapter design; interop obligations named as contracts are fine)
+- [ ] Focused on user value and business needs
+- [ ] Written for non-technical stakeholders
+- [ ] Change summary states what is changing and why
+
+## Delta Completeness
+
+- [ ] Every item sits under ADDED, MODIFIED or REMOVED (an empty section states None)
+- [ ] MODIFIED items state both sides (was -> now)
+- [ ] New behaviour is a user story (US-n) with priority, Given/When/Then acceptance, and an independent test
+- [ ] New or changed system requirements keep EARS form
+- [ ] Requirements are testable and unambiguous
+- [ ] No [NEEDS CLARIFICATION] markers remain
+
+## Domain Lift (Constraints / Classification / Contracts)
+
+- [ ] Constraint / NFR changes are captured as CN- items, or the section states None
+- [ ] Data sensitivity or exposure changes are captured as DC- items, or the section states None
+- [ ] External interoperability changes are captured as IC- items at contract level, or the section states None
+
+## Experience Lift (UI / UX standards)
+
+- [ ] Experience-standard changes are captured as UX- items, or the section states None
+- [ ] Where UX- deltas exist, each states a project-wide standard checkable on any surface — no screen, page, layout, navigation or component
+- [ ] Where UX- deltas exist, a change to THIS aggregate's own interaction behaviour is an FR- delta, not a UX- one
+- [ ] Where UX- deltas exist, a bound the service must meet stays a CN-, not a UX-
+
+## Merge Readiness
+
+- [ ] Header is complete: aggregate, change type, base version
+- [ ] Impact lists the affected ids (FR / BR / CN / DC / IC / UX / US / SC)
+- [ ] Regression risk names the existing behaviour that must still hold
+- [ ] Scoped to THIS change — the unchanged master is neither restated here nor edited
+
+## Notes
+
+- This checklist grades the DELTA DOCUMENT only. Accuracy against the master spec
+  (id continuity, conflicts with existing requirements) is checked downstream by
+  /appweaver analyze-delta-design.
+- Items marked incomplete require delta-spec updates before /appweaver design
+"@ } else { @"
+# Specification Quality Checklist: $featureName
+
+**Purpose**: Validate specification completeness and quality before proceeding to design
+**Created**: $today
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [ ] No implementation mechanics (languages, frameworks, code/adapter design; interop obligations named as contracts are fine)
+- [ ] Focused on user value and business needs
+- [ ] Written for non-technical stakeholders
+- [ ] All mandatory sections completed
+
+## Requirement Completeness
+
+- [ ] No [NEEDS CLARIFICATION] markers remain
+- [ ] Requirements are testable and unambiguous
+- [ ] Success criteria are measurable
+- [ ] Success criteria are technology-agnostic (no implementation details)
+- [ ] All acceptance scenarios are defined
+- [ ] Edge cases are identified
+- [ ] Scope is clearly bounded
+- [ ] Dependencies and assumptions identified
+
+## Domain Lift (Constraints / Classification / Contracts)
+
+- [ ] Domain-derived constraints are captured in Constraints & NFRs (CN-), or the section states None
+- [ ] Data sensitivity and exposure rules are captured in Data Classification (DC-), or the section states None
+- [ ] External interoperability obligations are captured as Integration Contracts (IC-) at contract level, or the section states None
+
+## Experience Lift (UI / UX standards)
+
+- [ ] Experience Scope states the actors, channels and device / browser / assistive-technology floors, or states None
+- [ ] Project-wide experience standards are captured as UX- items, or the section states None
+- [ ] Where UX- items exist, each is checkable on any surface — no screen, page, layout, navigation or component appears
+- [ ] Where UX- items exist, none of them is a per-feature interaction behaviour — those stay FR-
+- [ ] Where UX- items exist, a bound the SERVICE must meet is a CN-, cross-referenced where the obligation binds both lanes
+
+## Feature Readiness
+
+- [ ] All functional requirements have clear acceptance criteria
+- [ ] User scenarios cover primary flows
+- [ ] Feature meets measurable outcomes defined in Success Criteria
+- [ ] No implementation details leak into specification
+
+## Notes
+
+- Items marked incomplete require spec updates before /appweaver design
+"@ }
+    Set-Content -Path $checklistFile -Value $content -Encoding UTF8
+    Write-Json ([ordered]@{ checklist_file = $checklistFile; kind = $kind; target = $targetFile; created = $created })
+}
+
+# ─────────────────────────── list-domains ──────────────────────────────────
+# The selectable projects: immediate subdirs of guardrails/projects/ that carry a rule
+# map. The map is what makes a directory a project, exactly as a *.pack.txt is what makes
+# a foundations/ directory a foundation — without that test any stray sibling would be
+# offered as a governance target. EITHER map qualifies, because onboard writes the domain
+# map several steps before the technical one and a half-built project must stay visible.
+function Invoke-ListDomains {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $base = Join-Path $repo 'guardrails/projects'
+    $domains = @()
+    if (Test-Path $base) {
+        $domains = @(Get-ChildItem -Directory $base -ErrorAction SilentlyContinue | Where-Object {
+            (Test-Path (Join-Path $_.FullName 'tech-rule-bindings.md')) -or
+            (Test-Path (Join-Path $_.FullName 'domain-rule-bindings.md'))
+        } | ForEach-Object { $_.Name })
+    }
+    Write-Json ([ordered]@{ domains = @($domains) })
+}
+
+# ─────────────────────────── set-domain ────────────────────────────────────
+function Invoke-SetDomain {
+    param([string[]]$Rest)
+    $domain = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        if ($Rest[$i] -in '--domain','-Domain') { $domain = $Rest[++$i] }
+    }
+    if (-not $domain) { Write-Error 'set-domain: --domain is required'; exit 1 }
+
+    $repo = Get-RepoRoot
+    $mapRel = "guardrails/projects/$domain/domain-rule-bindings.md"
+    $mapExists = Test-Path (Join-Path $repo $mapRel)
+
+    New-Item -ItemType Directory -Force -Path (Join-Path $repo '.appweaver') | Out-Null
+    @{ domain = $domain } | ConvertTo-Json -Compress |
+        Set-Content -Path (Join-Path $repo '.appweaver/domain.json') -Encoding UTF8
+
+    Write-Json ([ordered]@{
+        domain     = $domain
+        map_path   = $mapRel
+        map_exists = $mapExists
+        written    = $true
+    })
+}
+
+# ────── stack-list / stack-detect / lane-declare / lane-resolve / lane-probe ──────
+# The lane model. Twins of the bash cmd_stack_list / cmd_stack_detect /
+# cmd_lane_declare / cmd_lane_resolve / cmd_lane_probe: both shells delegate to the
+# SAME python core, so the JSON contract has one implementation and the pair cannot
+# drift.
+#
+# lane-declare is the SOLE WRITER of .appweaver/stacks.json, with two callers:
+# aw-spec-select-stack, where a person picks, and aw-spec-onboard, which declares
+# what it reverse-engineered (those lanes carry origin: reverse-engineered, and
+# onboard never overwrites a lane that is already declared). stack-detect proposes
+# candidates and writes nothing. lane-resolve can never write — which is why these
+# are separate subcommands rather than one with a mode flag.
+function Invoke-AwStackCore {
+    param([string]$Op, [string[]]$Rest)
+    $py = Get-Py
+    if (-not $py) { Write-Error 'aw-stack: python3 is required for the lane model'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-stack.py'
+    if (-not (Test-Path $core)) { Write-Error "aw-stack: core not found at $core"; exit 1 }
+    $repo = Get-RepoRoot
+    & $py $core '--repo' $repo $Op @Rest
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
+function Invoke-StackList {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--kind'          { $fwd += '--kind'; $fwd += $Rest[++$i] }
+            '--preselect'     { $fwd += '--preselect'; $fwd += $Rest[++$i] }
+            '--include-none'  { $fwd += '--include-none' }
+            '--suggest'       { $fwd += '--suggest' }
+            default { Write-Error "stack-list: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'list' -Rest $fwd
+}
+
+function Invoke-StackDetect {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--kind'          { $fwd += '--kind'; $fwd += $Rest[++$i] }
+            '--exclude-root'  { $fwd += '--exclude-root'; $fwd += $Rest[++$i] }
+            default { Write-Error "stack-detect: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'detect' -Rest $fwd
+}
+
+function Invoke-LaneDeclare {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            # --source-path is the same field as --root; both spellings reach the core.
+            { $_ -in '--profile','--kind','--id','--root','--source-path','--stack','--origin','--build','--test','--run','--prototype-root','--prototype-run' } {
+                $fwd += $Rest[$i]; $fwd += $Rest[++$i]
+            }
+            '--no-prototype'          { $fwd += '--no-prototype' }
+            '--require-existing-root' { $fwd += '--require-existing-root' }
+            default { Write-Error "lane-declare: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'declare' -Rest $fwd
+}
+
+function Invoke-LaneResolve {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--kind','--id' } { $fwd += $Rest[$i]; $fwd += $Rest[++$i] }
+            default { Write-Error "lane-resolve: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'resolve' -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 source path is declared
+# before implement creates it.
+function Invoke-LaneVerify {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--require'             { $fwd += '--require'; $fwd += $Rest[++$i] }
+            # --flag=value: --command carries a phase name that starts with '/'.
+            '--command'             { $fwd += ('--command=' + $Rest[++$i]) }
+            '--allow-missing-root'  { $fwd += '--allow-missing-root' }
+            default { Write-Error "lane-verify: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'verify' -Rest $fwd
+}
+
+# Evidence that a lane of this kind exists, from the FILE signals only: a lane in
+# stacks.json, and a stack name appearing in free prose. The authoritative signal
+# — whether the active project's technical map carries `## /aw-spec-<command>` for the
+# lane's phases — is resolve-tech's, and callers OR the two together.
+function Invoke-LaneProbe {
+    param([string[]]$Rest)
+    $fwd = @()
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            # --flag=value, not two tokens: --hint carries raw user prose, and a value
+            # that starts with '-' reads as another flag when passed separately.
+            { $_ -in '--kind','--hint' } { $fwd += ($Rest[$i] + '=' + $Rest[++$i]) }
+            default { Write-Error "lane-probe: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    Invoke-AwStackCore -Op 'probe' -Rest $fwd
+}
+
+# ─────────────────────────── list-features ─────────────────────────────────
+# Twin of bash cmd_list_features: MERGE two feature sources, deduped by name
+# (case-insensitive) — (1) specs/ sub-folders (already scaffolded/adopted) and
+# (2) the OKF bundle's Aggregate concepts (the brownfield feature map, resolved by
+# the SAME shared python core the bash twin calls). Empty source 2 on greenfield.
+function Invoke-ListFeatures {
+    param([string[]]$Rest)
+    $preselect = ''; $bundle = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        if ($Rest[$i] -in '--preselect','-Preselect') { $preselect = $Rest[++$i] }
+        elseif ($Rest[$i] -in '--bundle','-Bundle')   { $bundle    = $Rest[++$i] }
+    }
+    $repo = Get-RepoRoot
+    $base = Join-Path $repo 'specs'
+    $sentinel = '+ Create a new feature'
+    if (-not $bundle) { $bundle = 'knowledge' }
+    if (-not [System.IO.Path]::IsPathRooted($bundle)) { $bundle = Join-Path $repo $bundle }
+
+    # Best-effort OKF aggregate list (brownfield feature map). Empty on greenfield.
+    $okfAggs = @()
+    $py = Get-Py; $invpy = Join-Path $PSScriptRoot '..' 'python' 'aw-inventory.py'
+    if ($py -and (Test-Path $bundle) -and (Test-Path $invpy)) {
+        try {
+            $okfRaw = & $py $invpy list-aggregates --bundle $bundle 2>$null
+            if ($okfRaw) { $okfAggs = @((($okfRaw | ConvertFrom-Json).aggregates)) }
+        } catch { $okfAggs = @() }
+    }
+
+    $features = @(); $names = @(); $seen = @{}
+    if (Test-Path $base) {
+        foreach ($d in (Get-ChildItem -Directory $base -ErrorAction SilentlyContinue | Sort-Object Name)) {
+            $ver = ''; $activeChange = ''
+            $avf = Join-Path $d.FullName 'active_version.json'
+            if (Test-Path $avf) { try { $av = Get-Content $avf -Raw | ConvertFrom-Json; $ver = "$($av.version)"; $activeChange = "$($av.active_change)" } catch { $ver = '' } }
+            $names += $d.Name; $seen[$d.Name.ToLower()] = $true
+            $features += [ordered]@{
+                name          = $d.Name
+                dir           = "specs/$($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
+                version       = $ver
+                active_change = $activeChange
+            }
+        }
+    }
+    # Merge OKF-discovered aggregates not already scaffolded under specs/.
+    foreach ($agg in $okfAggs) {
+        $nm = "$($agg.name)".Trim()
+        if (-not $nm -or $seen.ContainsKey($nm.ToLower())) { continue }
+        $names += $nm; $seen[$nm.ToLower()] = $true
+        $features += [ordered]@{
+            name          = $nm
+            dir           = "specs/$nm"
+            source        = 'okf'
+            has_spec      = $false
+            adopted       = $false
+            concept_path  = "$($agg.concept_path)"
+            design_docs   = 0
+            version       = ''
+            active_change = ''
+        }
+    }
+    # select_options = merged names + (injected new --preselect) + sentinel.
+    $opts = @($names)
+    if ($preselect -and (-not $seen.ContainsKey($preselect.ToLower()))) { $opts += $preselect }
+    $opts += $sentinel
+    Write-Json ([ordered]@{
+        features       = @($features)
+        names          = @($names)
+        count          = $names.Count
+        select_options = @($opts)
+        sentinel       = $sentinel
+    })
+}
+
+# ─────────────────────────── set-feature ───────────────────────────────────
+function Invoke-SetFeature {
+    param([string[]]$Rest)
+    $raw = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        if ($Rest[$i] -in '--feature','-Feature') { $raw = $Rest[++$i] }
+    }
+    if (-not $raw) { Write-Error 'set-feature: --feature is required'; exit 1 }
+
+    # Normalize to a PascalCase aggregate identifier (feature = aggregate).
+    $cleaned = ($raw -replace '[^A-Za-z0-9]+', ' ').Trim()
+    $feature = ConvertTo-Pascal -In $cleaned
+    if ($feature -notmatch '^[A-Za-z][A-Za-z0-9]*$') {
+        Write-Error "set-feature: '$raw' is not a valid feature name (need a letter-led alphanumeric aggregate, e.g. Order)"; exit 1
+    }
+
+    $repo = Get-RepoRoot
+    $featureDirRel = "specs/$feature"
+    $featureDir = Join-Path $repo $featureDirRel
+    $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
+    @{ feature_directory = $featureDirRel } | ConvertTo-Json -Compress |
+        Set-Content -Path (Join-Path $repo '.appweaver/feature.json') -Encoding UTF8
+
+    Write-Json ([ordered]@{
+        feature     = $feature
+        feature_dir = $featureDirRel
+        spec_file   = "$featureDirRel/spec.md"
+        existed     = [bool]$existed
+        created     = (-not $existed)
+        spec_exists = (Test-Path (Join-Path $featureDir 'spec.md'))
+    })
+}
+
+# ═══════════════════════════ active_version.json ════════════════════════════
+# Per-feature version state. Shells out to the SAME python as the bash twin so the
+# bump/timestamp logic is byte-identical across shells. (See bash _active_version.)
+$PyActiveVersion = @'
+import json, os, re, datetime, sys
+fd = os.environ["AW_FD"]; op = os.environ["AW_OP"]; cr = os.environ.get("AW_CR", "")
+force = os.environ.get("AW_FORCE", "")
+path = os.path.join(fd, "active_version.json")
+feature = os.path.basename(fd.rstrip("/"))
+def now(): return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+def load():
+    if os.path.isfile(path):
+        try: return json.load(open(path, encoding="utf-8")), True
+        except Exception: pass
+    return {"feature": feature, "version": "v1.0", "active_change": "", "updated": now()}, False
+def save(d):
+    d["updated"] = now()
+    open(path, "w", encoding="utf-8").write(json.dumps(d, indent=2) + "\n")
+def bump(v):
+    m = re.match(r'v?(\d+)(?:\.(\d+))?', (v or "v1.0").strip())
+    maj = int(m.group(1)) if m else 1
+    mnr = int(m.group(2)) if (m and m.group(2)) else 0
+    return "v%d.%d" % (maj, mnr + 1)
+
+d, existed = load()
+d.setdefault("feature", feature); d.setdefault("version", "v1.0"); d.setdefault("active_change", "")
+out = {"feature": d["feature"], "version": d["version"], "active_change": d.get("active_change", ""),
+       "exists": existed, "path": "active_version.json", "ok": True}
+if op == "read":
+    pass
+elif op == "init":
+    if not existed: save(d)
+    out["created"] = (not existed)
+elif op == "open":
+    cur = d.get("active_change", "")
+    if cur and cur != cr and force != "1":       # a DIFFERENT change is already open -> refuse
+        out["ok"] = False
+        out["error"] = ("change '%s' is already open on this feature; finish it "
+                        "(finalize-delta -> analyze-slice -> close-delta) before opening "
+                        "'%s', or pass --force" % (cur, cr))
+        out["conflict"] = cur; out["requested"] = cr; out["has_change"] = True
+        print(json.dumps(out)); sys.exit(3)
+    d["active_change"] = cr; save(d)
+    out["active_change"] = cr; out["opened"] = cr
+    if cur and cur == cr: out["reopened"] = True   # idempotent re-open of the same CR
+elif op == "close":
+    prev = d["version"]; closed = d.get("active_change", "")
+    if closed:                       # a real change was open -> materialized -> bump
+        d["version"] = bump(prev)
+    d["active_change"] = ""; save(d)
+    out["version"] = d["version"]; out["active_change"] = ""
+    out["previous"] = prev; out["closed_change"] = closed
+out["has_change"] = bool(out.get("active_change", ""))   # clean branch signal for design
+# What a close from THIS state would produce. One bump() authority, read by BOTH
+# finalize-delta (to write the right number into the Change History rows it appends)
+# and close-delta (which actually performs the bump and stamps the two headers), so
+# the two stages can never disagree about the target. Equals `version` when no change
+# is open, mirroring close's "only bump if a change was really open" guard.
+out["next_version"] = bump(out["version"]) if out.get("active_change", "") else out["version"]
+print(json.dumps(out))
+'@
+
+function Invoke-ActiveVersion {
+    param([string]$FeatureDir, [string]$Op, [string]$CrId = '', [string]$Force = '')
+    $py = Get-Py; if (-not $py) { Write-Error "version-$Op`: python3 required"; exit 1 }
+    $env:AW_FD = $FeatureDir; $env:AW_OP = $Op; $env:AW_CR = $CrId; $env:AW_FORCE = $Force
+    $PyActiveVersion | & $py -   # sets $LASTEXITCODE=3 when op=open is refused (guard)
+}
+
+function Invoke-VersionState {   # op in read|init (feature-dir only)
+    param([string]$Op, [string[]]$Rest)
+    $fdArg = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { if ($Rest[$i] -in '--feature-dir','-FeatureDir') { $fdArg = $Rest[++$i] } }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error "version-$Op`: no feature set and no --feature-dir"; exit 1 }
+    Invoke-ActiveVersion -FeatureDir $fd -Op $Op
+}
+
+
+
+# ─────────────────────────── feature-paths ─────────────────────────────────
+function Invoke-FeaturePaths {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $fj = Join-Path $repo '.appweaver/feature.json'
+    $fd = ''
+    if (Test-Path $fj) {
+        try { $fd = (Get-Content $fj -Raw | ConvertFrom-Json).feature_directory } catch { $fd = '' }
+    }
+    if (-not $fd) { Write-Error 'feature-paths: no feature set (run /appweaver select-feature first)'; exit 1 }
+    if (-not [System.IO.Path]::IsPathRooted($fd)) { $fd = Join-Path $repo $fd }
+    $feature = Split-Path $fd -Leaf   # the aggregate name (feature = specs/<Feature>)
+    # The master documents of a feature: spec.md (WHAT/WHY) + design.md (the service
+    # lane's HOW) + design.ui.md (the frontend lane's HOW, where the feature has a UI
+    # half). plan.md / tasks.md belonged to the retired /aw-spec-plan + /aw-spec-tasks
+    # phases and had zero consumers.
+    #
+    # ui_design_exists IS THE UI-HALF SIGNAL for the whole CR loop. Every delta stage
+    # asks the same question — is there a UI master to keep in sync? — and the master's
+    # own presence answers it without re-deriving the lane declaration and the slice's
+    # UI file count at each stage. It is also self-correcting: whatever authors
+    # design.ui.md (adopt today) enrolls the feature in the UI half of the delta loop
+    # by the act of writing the file.
+    $spec = Join-Path $fd 'spec.md'
+    $design = Join-Path $fd 'design.md'
+    $uiDesign = Join-Path $fd 'design.ui.md'
+    Write-Json ([ordered]@{
+        feature          = $feature
+        feature_dir      = $fd
+        spec_file        = $spec
+        design_file      = $design
+        ui_design_file   = $uiDesign
+        spec_exists      = (Test-Path $spec)
+        design_exists    = (Test-Path $design)
+        ui_design_exists = (Test-Path $uiDesign)
+    })
+}
+
+# ────────────────────────── checklist-read / -apply ────────────────────────
+function Get-CheckboxLines {
+    param([string[]]$Lines)
+    $fence = $false; $n = 0; $items = @()
+    for ($i = 0; $i -lt $Lines.Count; $i++) {
+        $line = [string]$Lines[$i]
+        if ($line.Trim().StartsWith('```')) { $fence = -not $fence; continue }
+        if ($fence) { continue }
+        $m = [regex]::Match($line, '^\s*- \[([ xX])\]\s?(.*)$')
+        if ($m.Success) {
+            $n++
+            $items += [pscustomobject]@{
+                n = $n; index = $i
+                checked = ($m.Groups[1].Value -match '[xX]')
+                text = $m.Groups[2].Value.Trim()
+            }
+        }
+    }
+    return ,$items
+}
+
+function Invoke-ChecklistRead {
+    param([string[]]$Rest)
+    $file = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { if ($Rest[$i] -eq '--file') { $file = $Rest[++$i] } }
+    if (-not $file) { Write-Error 'checklist-read: --file required'; exit 1 }
+    if (-not (Test-Path $file)) { Write-Json ([ordered]@{ exists = $false; total = 0; checked = 0; items = @() }); return }
+    $lines = Get-Content $file
+    $items = Get-CheckboxLines -Lines $lines
+    Write-Json ([ordered]@{
+        exists = $true; total = $items.Count
+        checked = @($items | Where-Object { $_.checked }).Count
+        items = @($items | ForEach-Object { [ordered]@{ n = $_.n; checked = $_.checked; text = $_.text } })
+    })
+}
+
+function Invoke-ChecklistApply {
+    param([string[]]$Rest)
+    $file = ''; $resultsRaw = '{}'
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) { '--file' { $file = $Rest[++$i] } '--results' { $resultsRaw = $Rest[++$i] } }
+    }
+    if (-not $file) { Write-Error 'checklist-apply: --file required'; exit 1 }
+    if (-not (Test-Path $file)) { Write-Json ([ordered]@{ exists = $false; before_checked = 0; after_checked = 0; total = 0; newly_passing = @(); regressions = @() }); return }
+    $results = @{}
+    try { (ConvertFrom-Json $resultsRaw).PSObject.Properties | ForEach-Object { $results[[int]$_.Name] = [bool]$_.Value } } catch {}
+    $lines = Get-Content $file
+    $items = Get-CheckboxLines -Lines $lines
+    $before = @($items | Where-Object { $_.checked }).Count
+    $newly = @(); $regress = @(); $after = 0
+    foreach ($it in $items) {
+        $desired = if ($results.ContainsKey($it.n)) { $results[$it.n] } else { $it.checked }
+        if ($desired -ne $it.checked) { if ($desired) { $newly += $it.n } else { $regress += $it.n } }
+        if ($desired) { $after++ }
+        $marker = if ($desired) { 'x' } else { ' ' }
+        $lines[$it.index] = $lines[$it.index] -replace '^(\s*- \[)[ xX](\].*)$', "`$1$marker`$2"
+    }
+    Set-Content -Path $file -Value $lines -Encoding UTF8
+    Write-Json ([ordered]@{ exists = $true; before_checked = $before; after_checked = $after; total = $items.Count; newly_passing = @($newly); regressions = @($regress) })
+}
+
+
+
+# ─────────────────────────────── detect-project ────────────────────────────
+# Project Structure Gate: is there a scaffolded app (not just framework files)?
+#
+# EVERY ecosystem's manifest is searched to the same depth. A project is where its
+# manifest is, not where the repository root is: a Maven service copied into
+# backend/orderservice/ is as scaffolded as a .sln at the top. Searching *.sln
+# recursively while testing pom.xml and package.json only at the root reported
+# every non-.NET layout that nests its project as no-project-at-all, which reads
+# at the gate as "run /appweaver foundation first" — advice a stack with no
+# foundation bundle cannot take.
+#
+# --root scopes the search to one lane's subtree: the directory the calling phase
+# is about to write into, so the answer is about that lane's project rather than
+# about any project anywhere. It falls back to the whole repository when the
+# subtree holds no manifest of its own, which is the ordinary .NET layout — a
+# lane rooted at src/ under a solution file that sits beside it.
+function Get-ProjectMarkers {
+    param([string]$Repo, [string]$Start)
+    # Anchored at the top level for the framework directories and at any depth for
+    # node_modules, matching the twin's -path/-name split.
+    $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 |
+            ForEach-Object { $_.FullName.Substring($Repo.Length).TrimStart('\','/') -replace '\\','/' } |
+            Where-Object {
+                $seg = $_.Split('/')
+                (-not ($topPrune -contains $seg[0])) -and (-not ($seg -contains 'node_modules'))
+            } |
+            Sort-Object -Unique -CaseSensitive | Select-Object -First 20
+    )
+    # Returned unwrapped so the caller's += appends the paths rather than the array.
+    return $out
+}
+
+function Invoke-DetectProject {
+    param([string[]]$Rest)
+    $scopeRoot = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--root','--source-path','-Root' } { $scopeRoot = $Rest[++$i] }
+        }
+    }
+    $repo = Get-RepoRoot
+    $scope = 'repo'
+    $start = $repo
+    # A lane's source path arrives as the value declare stored, so it may carry a
+    # trailing slash; an option label ("path  — why") never reaches a script argument.
+    $rel = ($scopeRoot -replace '\\','/').TrimStart('.','/').TrimEnd('/')
+    if ($rel -and (Test-Path -PathType Container (Join-Path $repo $rel))) {
+        $start = (Join-Path $repo $rel); $scope = 'lane'
+    }
+    $markers = @(Get-ProjectMarkers -Repo $repo -Start $start)
+    if ($markers.Count -eq 0 -and $scope -eq 'lane') {
+        $scope = 'repo'
+        $markers = @(Get-ProjectMarkers -Repo $repo -Start $repo)
+    }
+    Write-Json ([ordered]@{ scaffolded = ($markers.Count -gt 0); markers = @($markers); scope = $scope })
+}
+
+
+# ───────────────────────── foundation resolution ───────────────────────────
+# Foundations live at foundations/<stack>/<Name>/, grouped by the technology stack
+# they scaffold. Names are unique across stacks, so callers pass a bare <Name> and
+# the lookup searches every stack. A stack also holds siblings that are not foundations
+# (components/), so carrying a *.pack.txt is what makes a directory one — without that
+# test they surface as bundle-less foundations in every lookup.
+function Get-FoundationDirs {
+    param([string]$Repo)
+    $root = Join-Path $Repo 'foundations'
+    $out = @()
+    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 }
+                $out += [pscustomobject]@{ Name = $d.Name; Stack = $s.Name; Dir = $d.FullName; Rel = "foundations/$($s.Name)/$($d.Name)" }
+            }
+        }
+    }
+    # Returned unwrapped: call sites pipe this into Where-Object, and a ,$out wrapper
+    # would hand the pipeline the array itself as one object instead of its elements.
+    return $out
+}
+
+# ──────────────────────────── foundation-list ──────────────────────────────
+# List available foundations (foundations/<stack>/<Name>/ with a real <Name>.pack.txt)
+# for the user to PICK — deterministic, no LLM. Optional --args fast path mirrors bash.
+function Invoke-FoundationList {
+    param([string[]]$Rest)
+    $raw = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { '--args' { $raw = $Rest[++$i] } } }
+    $repo = Get-RepoRoot
+
+    # WHICH foundations this repo may be offered. A foundation bundle is a whole
+    # compiling project in one ecosystem's languages and build system, so unpacking a
+    # .NET one into a Spring repo does not produce a scaffold — it produces a second,
+    # foreign project beside the real one. The declared lanes already say which
+    # ecosystems this repo is, so filter to those and let the gate say why when that
+    # leaves nothing. Nothing declared (a bare greenfield repo, before select-stack)
+    # filters nothing: there is no answer yet to filter on.
+    $laneEcos = @(Get-Ecosystems)
+    $foundations = @(); $all = @(); $ecoOf = @()
+    foreach ($f in @(Get-FoundationDirs $repo)) {
+        if (-not (Test-Path (Join-Path $f.Dir "$($f.Name).pack.txt"))) { continue }
+        $all += $f.Name; $ecoOf += $f.Stack
+        if ($laneEcos.Count -eq 0 -or $laneEcos -contains $f.Stack) { $foundations += $f.Name }
+    }
+    $preName = ''; $preApp = ''; $outDir = '.'
+    if ($raw) { $t = $raw -split '\s+' | Where-Object { $_ }; if ($t.Count -ge 1) { $preName = $t[0] }; if ($t.Count -ge 2) { $preApp = $t[1] }; if ($t.Count -ge 3) { $outDir = $t[2] } }
+    $match = if ($foundations -contains $preName) { $preName } else { '' }
+    Write-Json ([ordered]@{
+        foundations = @($foundations); count = $foundations.Count
+        all_foundations = @($all); all_count = $all.Count
+        ecosystems = @($ecoOf); lane_ecosystems = @($laneEcos)
+        filtered = ($laneEcos.Count -gt 0)
+        preselect_name = $match; preselect_app = $preApp; out_dir = $outDir
+    })
+}
+
+function Invoke-FoundationLocate {
+    param([string[]]$Rest)
+    $name = ''; $app = ''; $out = '.'; $raw = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { '--name' { $name = $Rest[++$i] } '--app' { $app = $Rest[++$i] } '--out' { $out = $Rest[++$i] } '--args' { $raw = $Rest[++$i] } } }
+    if ($raw) { $t = $raw -split '\s+' | Where-Object { $_ }; if ($t.Count -ge 1) { $name = $t[0] }; if ($t.Count -ge 2) { $app = $t[1] }; if ($t.Count -ge 3) { $out = $t[2] } }
+    $repo = Get-RepoRoot
+    $dirs = @(Get-FoundationDirs $repo)
+    # available = every foundation dir (Get-FoundationDirs already requires a *.pack.txt)
+    $available = @($dirs | ForEach-Object { $_.Name })
+    function _fail($r) { Write-Json ([ordered]@{ ok = $false; reason = $r; available = @($available) }) }
+    if (-not $name -or -not $app) { _fail 'Usage: /aw-spec-foundation <FoundationName> <AppName> [OutputDirectory]'; return }
+    $found = $dirs | Where-Object { $_.Name -eq $name } | Select-Object -First 1
+    if (-not $found) { _fail "Foundation '$name' not found (expected foundations/<stack>/$name/)"; return }
+    $stack = $found.Stack; $rel = $found.Rel; $fdir = $found.Dir
+    $pack = Join-Path $fdir "$name.pack.txt"
+    if (-not (Test-Path $pack)) { _fail "Foundation '$name' has no bundle yet (expected $pack). Build it via the pack scripts in $rel/."; return }
+    $runner = ''; $unpacker = ''
+    if ((Get-Command pwsh -ErrorAction SilentlyContinue) -and (Test-Path (Join-Path $fdir 'unpack-foundation.ps1'))) { $runner = 'pwsh'; $unpacker = "$rel/unpack-foundation.ps1" }
+    elseif (Test-Path (Join-Path $fdir 'unpack-foundation.sh')) { $runner = 'sh'; $unpacker = "$rel/unpack-foundation.sh" }
+    else { _fail "No unpacker found in $rel/ (unpack-foundation.ps1 or .sh)"; return }
+    $header = (Get-Content $pack -TotalCount 30 | Where-Object { $_ -like '#*' }) -join "`n"
+    $sentinel = ''
+    $sm = [regex]::Match($header, '(?i)sentinel[^A-Za-z0-9_.]*([A-Za-z0-9_.]+)')
+    if ($sm.Success) { $sentinel = $sm.Groups[1].Value }
+    $fc = 0; $fm = [regex]::Match($header, '(?i)file[^0-9]*([0-9]+)'); if ($fm.Success) { $fc = [int]$fm.Groups[1].Value }
+    Write-Json ([ordered]@{
+        ok = $true; reason = ''; name = $name; stack = $stack; app = $app; out_dir = $out
+        pack_file = "$rel/$name.pack.txt"; unpacker = $unpacker; runner = $runner
+        sentinel = $sentinel; file_count = $fc; available = @($available)
+    })
+}
+
+# ─────────────────────────── foundation-unpack ─────────────────────────────
+function Invoke-FoundationUnpack {
+    param([string[]]$Rest)
+    $name = ''; $app = ''; $out = '.'; $dry = $false; $force = 'no'; $reference = $false
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) { '--name' { $name = $Rest[++$i] } '--app' { $app = $Rest[++$i] } '--out' { $out = $Rest[++$i] } '--dry-run' { $dry = $true } '--force' { $force = $Rest[++$i] } '--reference' { $reference = $true } }
+    }
+    if (-not $name -or -not $app) { Write-Error 'foundation-unpack: --name and --app required'; exit 1 }
+    $repo = Get-RepoRoot
+    $found = @(Get-FoundationDirs $repo) | Where-Object { $_.Name -eq $name } | Select-Object -First 1
+    $fdir = if ($found) { $found.Dir } else { Join-Path $repo "foundations/$name" }
+    $packbase = if ($reference) { "$name.Reference" } else { $name }
+    $stem = if ($reference) { 'unpack-reference-foundation' } else { 'unpack-foundation' }
+    $pack = Join-Path $fdir "$packbase.pack.txt"
+    if (-not (Test-Path $pack)) { Write-Json ([ordered]@{ ok = $false; mode = $(if ($dry) { 'dry' } else { 'real' }); written = 0; has_collisions = $false; stdout = "pack not found: $packbase.pack.txt" }); return }
+    $cmd = $null; $cargs = @()
+    if ((Get-Command pwsh -ErrorAction SilentlyContinue) -and (Test-Path (Join-Path $fdir "$stem.ps1"))) {
+        $cmd = 'pwsh'; $cargs = @('-NoProfile','-File',(Join-Path $fdir "$stem.ps1"),'-PackFile',$pack,'-TargetAppName',$app,'-OutDir',$out)
+        if ($dry) { $cargs += '-DryRun' }
+        if ($force -eq 'yes' -or $reference) { $cargs += '-Force' }
+    } elseif (Test-Path (Join-Path $fdir "$stem.sh")) {
+        $cmd = 'bash'; $cargs = @((Join-Path $fdir "$stem.sh"),'--pack-file',$pack,'--target-app-name',$app,'--out-dir',$out)
+        if ($dry) { $cargs += '--dry-run' }
+        if ($force -eq 'yes' -or $reference) { $cargs += '--force' }
+    } else { Write-Json ([ordered]@{ ok = $false; mode = 'real'; written = 0; has_collisions = $false; stdout = "no unpacker script for $name" }); return }
+    $outp = & $cmd @cargs 2>&1 | Out-String
+    $rc = $LASTEXITCODE
+    # unpackers say "Unpacked N file(s) to …" / "DryRun: N file(s) would be written …"
+    $written = 0; $wm = [regex]::Match($outp, '(?i)([0-9]+)\s+file'); if ($wm.Success) { $written = [int]$wm.Groups[1].Value }
+    $hasColl = ($dry -and $rc -ne 0)
+    Write-Json ([ordered]@{ ok = ($rc -eq 0); mode = $(if ($dry) { 'dry' } else { 'real' }); written = $written; has_collisions = $hasColl; stdout = ($outp.Substring([Math]::Max(0,$outp.Length-800))) })
+}
+
+# ─────────────────────── foundation-stash-dbcontext ────────────────────────
+function Invoke-FoundationStashDbContext {
+    param([string[]]$Rest)
+    $out = '.'
+    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
+    if (-not $ctx) { Write-Json ([ordered]@{ found = $false; dbcontext = ''; backup = '' }); return }
+    $bak = "$ctx.foundation.bak"
+    Copy-Item $ctx $bak
+    Write-Json ([ordered]@{ found = $true; dbcontext = $ctx; backup = $bak })
+}
+
+# ─────────────────────────── foundation-verify ─────────────────────────────
+function Invoke-FoundationVerify {
+    param([string[]]$Rest)
+    $out = '.'; $sentinel = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { '--out' { $out = $Rest[++$i] } '--sentinel' { $sentinel = $Rest[++$i] } } }
+    $repo = Get-RepoRoot
+    if (-not [System.IO.Path]::IsPathRooted($out)) { $out = Join-Path $repo $out }
+    $residue = @()
+    if ($sentinel -and (Test-Path $out)) {
+        # scan the generated tree only — exclude bundle/framework dirs
+        $residue = @(Get-ChildItem $out -Recurse -File -ErrorAction SilentlyContinue |
+            Where-Object { $_.FullName -notmatch '[/\\](\.git|guardrails|foundations|\.appweaver|specs|node_modules)[/\\]' } |
+            Where-Object { try { Select-String -Path $_.FullName -SimpleMatch $sentinel -Quiet -ErrorAction SilentlyContinue } catch { $false } } |
+            Select-Object -First 50 | ForEach-Object { $_.FullName.Substring($repo.Length).TrimStart('\','/') -replace '\\','/' })
+    }
+    Write-Json ([ordered]@{ clean = ($residue.Count -eq 0); residue = @($residue) })
+}
+
+# ─────────────────────────────── setup-constitution ────────────────────────
+# Ensure the split constitution files exist (copy from templates if missing):
+#   .appweaver/memory/constitution.technical.md  (from constitution-technical-template)
+#   .appweaver/memory/constitution.domain.md     (from constitution-domain-template)
+#   .appweaver/memory/constitution.ui.md         (from constitution-ui-template) — ONLY with --ui
+# The composed constitution.md is produced by compose-constitution after authoring.
+#
+# The UI half is opt-in because it is the only one whose ABSENCE is meaningful: a
+# backend-only project has no frontend lane and must look exactly as it did before
+# the lane model existed. The other two are always created and left as unauthored
+# templates when unused, which compose-constitution then skips.
+function Invoke-SetupConstitution {
+    param([string[]]$Rest)
+    # --ui / --no-technical follow the LANES the project declared. A half is a lane's
+    # standing governance, so a lane the project does not have gets no half — and the
+    # file is not created either, because an empty template left in memory/ is
+    # indistinguishable from a half somebody forgot to author.
+    $wantUi = $false; $wantTech = $true
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--ui'           { $wantUi = $true }
+            '--no-technical' { $wantTech = $false }
+            # An EMPTY argument is a flag slot the caller left unfilled. The engine builds
+            # a step's `args:` list before it knows which branch it is in, so a workflow
+            # that varies one flag has to choose between duplicating the whole step and
+            # passing '' — and duplicating it is how this call came to recreate the
+            # technical half that the earlier call had just been told to skip.
+            ''               { }
+            default { Write-Error "setup-constitution: unknown arg '$($Rest[$i])'"; exit 1 }
+        }
+    }
+    $repo = Get-RepoRoot
+    New-Item -ItemType Directory -Force -Path (Join-Path $repo '.appweaver/memory') | Out-Null
+    $tech = Join-Path $repo '.appweaver/memory/constitution.technical.md'
+    $dom  = Join-Path $repo '.appweaver/memory/constitution.domain.md'
+    $ui   = Join-Path $repo '.appweaver/memory/constitution.ui.md'
+    $techCreated = $false; $domCreated = $false; $uiCreated = $false; $uiPath = ''
+    # Full override/preset/extension/core resolution, matching the bash twin — and the
+    # same resolution the placeholder check reads the template's token vocabulary from,
+    # so a preset-supplied template is scored against itself rather than against core.
+    if (-not $wantTech) { $tech = '' }
+    if ($tech -and -not (Test-Path $tech)) {
+        $tpl = Resolve-NamedTemplate -Name 'constitution-technical-template' -RepoRoot $repo
+        if ($tpl) { Copy-Item $tpl $tech } else { New-Item -ItemType File -Force -Path $tech | Out-Null }
+        $techCreated = $true
+    }
+    if (-not (Test-Path $dom)) {
+        $tpl = Resolve-NamedTemplate -Name 'constitution-domain-template' -RepoRoot $repo
+        if ($tpl) { Copy-Item $tpl $dom } else { New-Item -ItemType File -Force -Path $dom | Out-Null }
+        $domCreated = $true
+    }
+    if ($wantUi) {
+        $uiPath = $ui
+        if (-not (Test-Path $ui)) {
+            $tpl = Resolve-NamedTemplate -Name 'constitution-ui-template' -RepoRoot $repo
+            if ($tpl) { Copy-Item $tpl $ui } else { New-Item -ItemType File -Force -Path $ui | Out-Null }
+            $uiCreated = $true
+        }
+    }
+    Write-Json ([ordered]@{ constitution_technical_file = $tech; constitution_domain_file = $dom; constitution_ui_file = $uiPath; technical_created = $techCreated; domain_created = $domCreated; ui_created = $uiCreated })
+}
+
+# ─────────────────────────────── compose-constitution ──────────────────────
+# Deterministically concatenate the authored halves into the composed
+# constitution.md (human/compat view; NOT loaded by the pipeline phases). A half
+# that is absent or still an unauthored template is skipped, so a technical-only
+# project's composed file mirrors the technical half exactly.
+#
+# Order is technical → domain → ui. The domain half's principles CONTINUE the
+# technical base's roman numerals from wherever that base ended, so those two stay
+# adjacent; the UI half runs a parallel UX-* series and appends without interrupting
+# that run.
+#
+# NUMBERING CHECK. The boundary between the two roman-numeral halves is derived per
+# project — the technical half runs to whatever length its mapped technology base
+# defines — so a base of eighteen principles and a domain half that assumed it could
+# start at XVI would silently produce two Principle XVIs. Composition is the one place
+# both halves are read together, so it is where that is caught. A collision sets
+# numbering_ok=false; the file is still written, because a composed view that shows the
+# clash is more useful for fixing it than no file at all.
+$script:RomanValues = @(
+    @(1000, 'M'), @(900, 'CM'), @(500, 'D'), @(400, 'CD'), @(100, 'C'), @(90, 'XC'),
+    @(50, 'L'), @(40, 'XL'), @(10, 'X'), @(9, 'IX'), @(5, 'V'), @(4, 'IV'), @(1, 'I')
+)
+
+function ConvertFrom-Roman {
+    param([string]$Roman)
+    $total = 0; $i = 0
+    foreach ($pair in $script:RomanValues) {
+        $val = $pair[0]; $sym = [string]$pair[1]
+        while (($i + $sym.Length) -le $Roman.Length -and $Roman.Substring($i, $sym.Length) -ceq $sym) {
+            $total += $val; $i += $sym.Length
+        }
+    }
+    if ($i -ne $Roman.Length) { return $null }
+    return $total
+}
+
+function ConvertTo-Roman {
+    param([int]$Value)
+    $sb = ''
+    foreach ($pair in $script:RomanValues) {
+        $val = $pair[0]; $sym = [string]$pair[1]
+        while ($Value -ge $val) { $sb += $sym; $Value -= $val }
+    }
+    return $sb
+}
+
+# UNFILLED-PLACEHOLDER TEST. "Still a raw template" is decided by intersecting the
+# half's [TOKEN]s with the TOKENS ITS OWN KIT TEMPLATE DEFINES — never by the shape of
+# the bracket. A constitution is free to write [HIPAA], [ISO_13485] or a [GDPR](url)
+# link; those are project content and match no template token, so they can no longer
+# make a whole ratified half vanish from the composed file.
+function Get-TemplateTokens {
+    param([string]$Name, [string]$RepoRoot)
+    $tpl = Resolve-NamedTemplate -Name $Name -RepoRoot $RepoRoot
+    if (-not $tpl) { return $null }
+    $set = @{}
+    foreach ($m in [regex]::Matches((Get-Content -Raw $tpl), '\[([A-Z][A-Z0-9_]*)\]')) {
+        $set[$m.Groups[1].Value] = $true
+    }
+    return $set
+}
+
+# The template's numbered slots are a series the author is told to extend, so
+# PRINCIPLE_6_NAME is as much an unfilled slot as PRINCIPLE_1_NAME even though the
+# template only shows five. Digit runs generalise; nothing else does, which is what keeps
+# a bracketed regulation code out of the family.
+function Test-TemplateToken {
+    param([string]$Token, [hashtable]$Known)
+    if ($Known.ContainsKey($Token)) { return $true }
+    if ($Token -notmatch '\d') { return $false }
+    foreach ($k in $Known.Keys) {
+        if ($k -match '\d') {
+            $rx = '\A' + ([regex]::Escape($k) -replace '\d+', '\d+') + '\Z'
+            if ($Token -cmatch $rx) { return $true }
+        }
+    }
+    return $false
+}
+
+# Tokens in the file that its template also defines. Comments are stripped first so a
+# Sync Impact Report NAMING the placeholders it filled ("Removed: [PROJECT_NAME]")
+# cannot be mistaken for the placeholders themselves.
+function Get-UnfilledTokens {
+    param([string]$Path, [hashtable]$Known)
+    $found = @()
+    if (-not (Test-Path $Path)) { return $found }
+    $body = [regex]::Replace((Get-Content -Raw $Path), '(?s)<!--.*?-->', '')
+    foreach ($m in [regex]::Matches($body, '\[([A-Z][A-Z0-9_]*)\]')) {
+        $t = $m.Groups[1].Value
+        if ($found -notcontains $t -and (Test-TemplateToken -Token $t -Known $Known)) { $found += $t }
+    }
+    return $found
+}
+
+# A principle heading opens with its numeral: "### VII — Name" or "### VII. Name".
+# UX-* is a PARALLEL series belonging to the frontend lane and is deliberately not
+# part of this run, so it is skipped rather than checked against it.
+function Get-PrincipleNumbers {
+    param([string]$Path)
+    # Callers wrap the result in @(), which is what guarantees array-ness for the
+    # empty and single-item cases; returning ,$found on top of that would nest.
+    $found = @()
+    if (-not (Test-Path $Path)) { return $found }
+    $text = Get-Content -Raw $Path
+    $body = [regex]::Replace($text, '<!--.*?-->', '', 'Singleline')
+    foreach ($m in [regex]::Matches($body, '(?m)^#{2,4}[ \t]+(UX-)?([IVXLCDM]+)[ \t]*[—–\-.:)]')) {
+        if ($m.Groups[1].Success) { continue }   # UX- series — parallel, not this sequence
+        $roman = $m.Groups[2].Value
+        $n = ConvertFrom-Roman -Roman $roman
+        # Round-trip + a sane ceiling keep ordinary words made of roman letters
+        # (and stray four-digit numerals) out of the sequence.
+        if ($null -ne $n -and $n -le 100 -and (ConvertTo-Roman -Value $n) -ceq $roman) {
+            # An object, not a nested array: PowerShell unrolls arrays-of-arrays on
+            # return and through the pipeline, which loses the pairing.
+            $found += [PSCustomObject]@{ N = $n; Roman = $roman }
+        }
+    }
+    return $found
+}
+
+function Invoke-ComposeConstitution {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $tech = Join-Path $repo '.appweaver/memory/constitution.technical.md'
+    $dom  = Join-Path $repo '.appweaver/memory/constitution.domain.md'
+    $ui   = Join-Path $repo '.appweaver/memory/constitution.ui.md'
+    $out  = Join-Path $repo '.appweaver/memory/constitution.md'
+    # A project that declared no SERVICE lane authors no technical half, and that is a
+    # complete constitution rather than a broken one — a UI-only project's governance is
+    # the UI half plus the domain addenda. What is not composable is a project with
+    # nothing at all, which means the halves were never authored.
+    $includeTech = Test-Path $tech
+    if (-not ($includeTech -or (Test-Path $dom) -or (Test-Path $ui))) {
+        Write-Json ([ordered]@{ composed_file = $out; ok = $false; technical_included = $false; domain_included = $false; ui_included = $false; numbering_ok = $true; numbering_checked = $false; issues = @('no constitution half found — run /appweaver constitution') }); return
+    }
+    $header = @(
+        '<!-- COMPOSED — generated by `aw-spec-actions compose-constitution`. Do not edit here.',
+        '     Source of truth: the constitution halves — technical + domain + ui (edit those).',
+        '     Pipeline phases load the halves directly; this composed view is for humans/compat. -->',
+        ''
+    ) -join "`n"
+    $body = $header + "`n"
+    if ($includeTech) { $body += (Get-Content -Raw $tech) }
+    # Include a half only if authored — non-empty AND carrying none of its own kit
+    # template's tokens (an unused half stays a raw template). A half whose template
+    # cannot be resolved is included: never drop one on a guess.
+    $tokDom = Get-TemplateTokens -Name 'constitution-domain-template' -RepoRoot $repo
+    $tokUi  = Get-TemplateTokens -Name 'constitution-ui-template' -RepoRoot $repo
+    $includeDomain = $false
+    if ((Test-Path $dom) -and ((Get-Item $dom).Length -gt 0)) {
+        $includeDomain = ($null -eq $tokDom) -or (@(Get-UnfilledTokens -Path $dom -Known $tokDom).Count -eq 0)
+    }
+    $includeUi = $false
+    if ((Test-Path $ui) -and ((Get-Item $ui).Length -gt 0)) {
+        $includeUi = ($null -eq $tokUi) -or (@(Get-UnfilledTokens -Path $ui -Known $tokUi).Count -eq 0)
+    }
+    if ($includeDomain) {
+        $body += "`n`n---`n`n" + (Get-Content -Raw $dom)
+    }
+    if ($includeUi) {
+        $body += "`n`n---`n`n" + (Get-Content -Raw $ui)
+    }
+    Set-Content -Path $out -Value $body -NoNewline
+
+    # ── principle numbering ────────────────────────────────────────────────
+    $techP = if ($includeTech) { @(Get-PrincipleNumbers -Path $tech) } else { @() }
+    $domP  = if ($includeDomain) { @(Get-PrincipleNumbers -Path $dom) } else { @() }
+    $issues = @()
+    $numberingOk = $true
+
+    # The cross-half check can only run on halves whose principles it can actually read.
+    # A half numbered some other way (1., 2. / P-01) parses to nothing, and silence there
+    # would look identical to a clean result — so say so instead of reporting all-clear.
+    $numberingForm = "principles must be headed '### I — Title' or '### I. Title' (the UI half runs its own UX-I, UX-II, … series)"
+    $numberingChecked = $true
+    if (-not $includeTech) {
+        # No service lane, so no technical half and no boundary to check: the domain
+        # half opens the roman-numeral sequence at I instead of continuing one. Not an
+        # issue, and not a check that silently passed — it is a check with no subject.
+        $numberingChecked = $false
+    } elseif ($techP.Count -eq 0) {
+        $numberingOk = $false; $numberingChecked = $false
+        $issues += ('no roman-numeral principle headings found in the technical half, so numbering could not be verified — ' + $numberingForm)
+    }
+    if ($includeDomain -and $domP.Count -eq 0) {
+        $numberingOk = $false; $numberingChecked = $false
+        $issues += ('no roman-numeral principle headings found in the domain half, so numbering could not be verified — ' + $numberingForm)
+    }
+
+    foreach ($set in @(@{ Items = $techP; Label = 'technical' }, @{ Items = $domP; Label = 'domain' })) {
+        $seen = @{}; $dup = @()
+        foreach ($p in $set.Items) {
+            if ($seen.ContainsKey($p.N) -and $dup -notcontains $p.Roman) { $dup += $p.Roman }
+            $seen[$p.N] = $true
+        }
+        if ($dup.Count -gt 0) {
+            $numberingOk = $false
+            $issues += ('{0} half reuses principle number(s): {1}' -f $set.Label, ($dup -join ', '))
+        }
+    }
+
+    if ($techP.Count -gt 0 -and $domP.Count -gt 0) {
+        $techNums = @($techP | ForEach-Object { $_.N })
+        $domNums  = @($domP  | ForEach-Object { $_.N })
+        $lastTech = ($techNums | Measure-Object -Maximum).Maximum
+        $firstDom = ($domNums | Measure-Object -Minimum).Minimum
+        $overlap = @($techNums | Where-Object { $domNums -contains $_ } | Sort-Object -Unique)
+        if ($overlap.Count -gt 0) {
+            $numberingOk = $false
+            $issues += ('principle number(s) {0} appear in BOTH the technical and domain halves — the domain half must resume from the number after the technical half''s last principle ({1}), not from a fixed value' -f (($overlap | ForEach-Object { ConvertTo-Roman -Value $_ }) -join ', '), (ConvertTo-Roman -Value $lastTech))
+        }
+        elseif ($firstDom -ne ($lastTech + 1)) {
+            $numberingOk = $false
+            $issues += ('domain half starts at {0} but the technical half ends at {1} — numbering must run unbroken across the two halves (expected {2})' -f (ConvertTo-Roman -Value $firstDom), (ConvertTo-Roman -Value $lastTech), (ConvertTo-Roman -Value ($lastTech + 1)))
+        }
+    }
+
+    Write-Json ([ordered]@{
+        composed_file     = $out
+        ok                = $numberingOk
+        domain_included   = $includeDomain
+        ui_included       = $includeUi
+        numbering_ok      = $numberingOk
+        numbering_checked = $numberingChecked
+        issues            = $issues
+        technical_last    = $(if ($techP.Count -gt 0) { ConvertTo-Roman -Value ((@($techP | ForEach-Object { $_.N }) | Measure-Object -Maximum).Maximum) } else { $null })
+        domain_first      = $(if ($domP.Count -gt 0) { ConvertTo-Roman -Value ((@($domP | ForEach-Object { $_.N }) | Measure-Object -Minimum).Minimum) } else { $null })
+    })
+}
+
+# ─────────────────────────── constitution-verify ───────────────────────────
+# Deterministic lint of a generated constitution (NO LLM): unfilled template
+# placeholders, body-vs-Sync-Impact-Report version agreement, and non-ISO dates.
+# Consumed by the constitution skill's bounded self-correction loop. ok=false => the
+# loop asks the model to patch.
+#
+# A placeholder is a token THE KIT TEMPLATE ACTUALLY DEFINES, resolved from the half's
+# own template and intersected with the file. Bracket SHAPE is not evidence: [HIPAA],
+# [ISO_13485] and [GDPR](url) are ordinary constitution content in a regulated domain
+# and must never be reported as unfilled slots. --template overrides the name derived
+# from the filename.
+#
+# The version is read from lines that OPEN with the label, last one wins, so an
+# "OpenAPI version 3.1.0" inside a principle cannot be mistaken for the document's
+# version. On a report line the LAST semver is the new version, which also survives an
+# "old -> new" whose arrow was mangled by an encoding round-trip.
+function Get-LabeledVersion {
+    param([string]$Text, [switch]$LastOnLine)
+    $vals = @()
+    foreach ($line in ($Text -split "`n")) {
+        if ($line -match '^[\s>*_#-]*version\b') {
+            $sem = @([regex]::Matches($line, '\d+\.\d+\.\d+') | ForEach-Object { $_.Value })
+            if ($sem.Count -gt 0) { $vals += $(if ($LastOnLine) { $sem[-1] } else { $sem[0] }) }
+        }
+    }
+    if ($vals.Count -gt 0) { return $vals[-1] } else { return $null }
+}
+function Invoke-ConstitutionVerify {
+    param([string[]]$Rest)
+    $file = ''; $template = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        if ($Rest[$i] -eq '--file') { $file = $Rest[++$i] }
+        elseif ($Rest[$i] -eq '--template') { $template = $Rest[++$i] }
+    }
+    if (-not $file) { Write-Error 'constitution-verify: --file required'; exit 1 }
+    if (-not (Test-Path $file)) {
+        Write-Json ([ordered]@{ ok = $false; exists = $false; issues = @('constitution file not found');
+            placeholders = @(); version_body = $null; version_report = $null; version_match = $null; bad_dates = @() })
+        return
+    }
+    if (-not $template) {
+        switch (Split-Path -Leaf $file) {
+            'constitution.technical.md' { $template = 'constitution-technical-template' }
+            'constitution.domain.md'    { $template = 'constitution-domain-template' }
+            'constitution.ui.md'        { $template = 'constitution-ui-template' }
+        }
+    }
+    $known = $null
+    if ($template) { $known = Get-TemplateTokens -Name $template -RepoRoot (Get-RepoRoot) }
+    $text = Get-Content -Path $file -Raw
+    # Strip HTML comments (template guidance + Sync Impact Report); keep the first as the report.
+    $cm = [regex]::Match($text, '(?s)<!--.*?-->')
+    $report = if ($cm.Success) { $cm.Value } else { '' }
+    $body = [regex]::Replace($text, '(?s)<!--.*?-->', '')
+    # 1. Unfilled slots = the file's [TOKEN]s intersected with the template's vocabulary.
+    $templateMissing = ($null -eq $known)
+    $placeholders = @()
+    if (-not $templateMissing) {
+        $placeholders = @([regex]::Matches($body, '\[([A-Z][A-Z0-9_]*)\]') |
+            ForEach-Object { $_.Groups[1].Value } |
+            Where-Object { Test-TemplateToken -Token $_ -Known $known } |
+            Select-Object -Unique | Sort-Object)
+    }
+    # 2. Version: the document's own labelled version line vs the report's "new" version.
+    $versionBody = Get-LabeledVersion $body
+    $arrow = [regex]::Match($report, '(\d+\.\d+\.\d+)\s*(?:->|→|=>)\s*(\d+\.\d+\.\d+)')
+    $versionReport = if ($arrow.Success) { $arrow.Groups[2].Value } else { Get-LabeledVersion $report -LastOnLine }
+    $versionMatch = $null
+    if ($versionBody -and $versionReport) { $versionMatch = ($versionBody -eq $versionReport) }
+    # 3. Obviously non-ISO dates on ratification/amended/date lines (ISO never matches these).
+    $bad = @()
+    foreach ($line in ($body -split "`n")) {
+        if ($line -match '(?i)ratif|amend|\bdate\b') {
+            foreach ($mm in [regex]::Matches($line, '\b\d{1,2}/\d{1,2}/\d{2,4}\b')) { $bad += $mm.Value }
+            foreach ($mm in [regex]::Matches($line, '\b\d{1,2}-\d{1,2}-\d{4}\b')) { $bad += $mm.Value }
+            foreach ($mm in [regex]::Matches($line, '\b(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2},?\s+\d{4}\b')) { $bad += $mm.Value }
+        }
+    }
+    $bad = @($bad | Select-Object -Unique | Sort-Object)
+    $issues = @()
+    if ($placeholders.Count -gt 0) { $issues += ("{0} unfilled placeholder(s): {1}" -f $placeholders.Count, ($placeholders -join ', ')) }
+    # Reported, not failed: a missing kit template is an install problem, and blocking
+    # the authoring loop over it would help nobody.
+    if ($templateMissing) { $issues += 'placeholder check skipped — no kit template resolved for this half' }
+    if ($versionMatch -eq $false) { $issues += ("version mismatch: body {0} vs Sync Impact Report {1}" -f $versionBody, $versionReport) }
+    if ($bad.Count -gt 0) { $issues += ("non-ISO date(s) (use YYYY-MM-DD): {0}" -f ($bad -join ', ')) }
+    $ok = ($placeholders.Count -eq 0) -and ($versionMatch -ne $false) -and ($bad.Count -eq 0)
+    Write-Json ([ordered]@{ ok = $ok; exists = $true; issues = @($issues);
+        placeholders = @($placeholders); placeholder_check = (-not $templateMissing);
+        version_body = $versionBody; version_report = $versionReport;
+        version_match = $versionMatch; bad_dates = @($bad) })
+}
+
+# ────────────────────────── agent-context-update ───────────────────────────
+function Invoke-AgentContextUpdate {
+    param([string[]]$Rest)
+    $plan = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { if ($Rest[$i] -eq '--plan') { $plan = $Rest[++$i] } }
+    $repo = Get-RepoRoot
+    $script = Join-Path $repo '.appweaver/extensions/agent-context/scripts/powershell/update-agent-context.ps1'
+    if (-not (Test-Path $script)) {
+        Write-Json ([ordered]@{ ok = $true; ran = $false; message = 'agent-context extension not installed; nothing to do' }); return
+    }
+    if ($plan) { $out = & pwsh -NoProfile -File $script $plan 2>&1 | Out-String }
+    else { $out = & pwsh -NoProfile -File $script 2>&1 | Out-String }
+    $rc = $LASTEXITCODE
+    Write-Json ([ordered]@{ ok = ($rc -eq 0); ran = $true; message = ($out.Substring([Math]::Max(0,$out.Length-400))).Trim() })
+}
+
+
+
+# ─────────────────────────────── list-components ───────────────────────────
+# Immediate subdirs of foundations/dotnet/components/ that contain an integration.md runbook.
+# Immediate subdirs of foundations/<ecosystem>/components/ that contain an integration.md
+# runbook, for the ecosystem the BACKEND lane declares. Components are wired into a host
+# project by editing its build files and its startup registration, so a component only
+# exists for the ecosystem whose build files and startup it knows how to edit — the
+# catalogue is per-ecosystem for the same reason the foundations are.
+function Invoke-ListComponents {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $eco = Get-LaneField -Field 'backend_ecosystem'
+    # No backend lane yet: 'dotnet' is the only ecosystem that ships components, so it is
+    # what an undeclared repo would have been shown before the lane model and stays the
+    # answer until select-stack says otherwise.
+    if (-not $eco) { $eco = 'dotnet' }
+    $base = Join-Path $repo "foundations/$eco/components"
+    $comps = @()
+    if (Test-Path $base) {
+        foreach ($d in (Get-ChildItem -Directory $base -ErrorAction SilentlyContinue)) {
+            if (Test-Path (Join-Path $d.FullName 'integration.md')) { $comps += $d.Name }
+        }
+    }
+    Write-Json ([ordered]@{ components = @($comps); ecosystem = $eco; dir = "foundations/$eco/components" })
+}
+
+# ─────────────────────────────── find-host-project ─────────────────────────
+# DELIBERATELY .NET-ONLY, and it reports which stack it looked at so a caller can say
+# so. 'Program.cs' is not a cross-stack concept: a Spring lane's entry point is an
+# @SpringBootApplication class, an Express lane's is whatever 'main' in package.json
+# names, and neither has the .csproj this returns. Callers that need a LAUNCH COMMAND
+# ask the lane instead (its declared 'run'); this exists for the two callers that need
+# the .NET host DIRECTORY. found:false on a non-.NET lane is the correct answer.
+function Invoke-FindHostProject {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    # WHERE the host lives. The service lane's declared source path when there is one,
+    # 'src' when there is not — the same question run-migrate asks, and the same answer.
+    $svcRoot = Get-LaneField -Field 'backend_root'
+    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
+    if (-not $prog) {
+        $prog = Get-ChildItem -Path $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
+    Write-Json ([ordered]@{ found = $true; program_cs = $prog; project_dir = $pdir; csproj = $(if ($csproj) { $csproj } else { '' }); ecosystem = $eco; searched = $searched })
+}
+
+# ─────────────────────────────── component-catalog ──────────────────────────
+# Deterministic parse of a component's integration.md "Implementation catalog"
+# markdown table (NO LLM). Returns {integrable, impl_keys[], implementations[{key,desc}]}.
+# Twin of the bash cmd_component_catalog: both shells delegate to the SAME python
+# core, so the parse and the JSON contract have one implementation and the pair
+# cannot drift.
+function Invoke-ComponentCatalog {
+    param([string[]]$Rest)
+    $file = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { if ($Rest[$i] -eq '--file') { $file = $Rest[++$i] } }
+    if (-not $file) { Write-Error 'component-catalog: --file required'; exit 1 }
+    $py = Get-Py
+    if (-not $py) { Write-Error 'component-catalog: python3 is required to parse the catalog'; exit 1 }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-component-catalog.py'
+    if (-not (Test-Path $core)) { Write-Error "component-catalog: core not found at $core"; exit 1 }
+    & $py $core '--repo' (Get-RepoRoot) '--file' $file
+    if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
+# ─────────────────────────────── component-verify ───────────────────────────
+# Post-wiring verification (NO LLM decision): dotnet build (graceful skip if absent) +
+# R0.2a dual-registration guard. Returns {ok, ran, build_ok, errors[],
+# dual_registration_ok, fix_target, fix_reason, can_fix}.
+function Get-DefiningFiles {
+    param([string]$Method, [string]$Root)
+    $hits = @()
+    if (-not $Root -or -not (Test-Path $Root)) { return , $hits }
+    $pat = '\b' + [regex]::Escape($Method) + '\s*\('
+    Get-ChildItem $Root -Recurse -File -Filter *.cs -ErrorAction SilentlyContinue |
+        Where-Object { $_.FullName -notmatch '[/\\](bin|obj|\.git)[/\\]' } |
+        ForEach-Object {
+            $txt = Get-Content $_.FullName -Raw -ErrorAction SilentlyContinue
+            if ($txt -and ($txt -match $pat)) { $hits += [pscustomobject]@{ path = $_.FullName; text = $txt } }
+        }
+    return , $hits
+}
+function Invoke-ComponentVerify {
+    param([string[]]$Rest)
+    $hostDir = ''; $hostCsproj = ''; $marker = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) { '--host-dir' { $hostDir = $Rest[++$i] } '--host-csproj' { $hostCsproj = $Rest[++$i] } '--marker' { $marker = $Rest[++$i] } }
+    }
+    $repo = Get-RepoRoot
+    $marker = $marker.Trim()
+    function RelP($p) { if ($p -and $repo) { try { return ([System.IO.Path]::GetRelativePath($repo, $p) -replace '\\', '/') } catch { return $p } } else { return $p } }
+    # --- (1) build ---
+    $ran = $false; $buildOk = $true; $errors = @(); $primary = ''
+    if (Get-Command dotnet -ErrorAction SilentlyContinue) {
+        $target = if ($hostCsproj) { $hostCsproj } else { $hostDir }
+        if ($target -and (Test-Path $target)) {
+            $ran = $true
+            $out = (& dotnet build $target -nologo 2>&1 | Out-String)
+            $code = $LASTEXITCODE
+            foreach ($line in ($out -split "`n")) { if ($line -match ':\s*error\s') { $errors += $line.Trim() } }
+            $errors = @($errors | Select-Object -Unique | Select-Object -First 20)
+            $buildOk = ($code -eq 0)
+            if (-not $buildOk -and $errors.Count -gt 0) {
+                $m = [regex]::Match($errors[0], '^(.*?)\(\d+,\d+\)'); if ($m.Success) { $primary = RelP ($m.Groups[1].Value.Trim()) }
+            }
+            if (-not $buildOk -and -not $primary -and $hostCsproj) { $primary = RelP $hostCsproj }
+        }
+    }
+    # --- (2) R0.2a dual-registration guard ---
+    $searchRoot = if ($hostDir -and (Test-Path $hostDir)) { $hostDir } else { $repo }
+    $infra = @(Get-DefiningFiles 'AddInfrastructure' $searchRoot)
+    $aspire = @(Get-DefiningFiles 'AddAspireInfrastructure' $searchRoot)
+    $dualApp = ($infra.Count -gt 0 -and $aspire.Count -gt 0)
+    $dualOk = $true; $dualNote = ''; $dualFix = ''
+    function Pick-Fix($hits) {
+        $nonProg = @($hits | Where-Object { [System.IO.Path]::GetFileName($_.path) -ne 'Program.cs' })
+        if ($nonProg.Count -gt 0) { return RelP $nonProg[0].path } elseif ($hits.Count -gt 0) { return RelP $hits[0].path } else { return '' }
+    }
+    if (-not $dualApp) { $dualNote = 'single registration path (R0.2) — dual-registration check N/A' }
+    elseif (-not $marker) { $dualNote = 'both AddInfrastructure and AddAspireInfrastructure exist; no marker provided to verify the component is in both' }
+    else {
+        $inInfra = @($infra | Where-Object { $_.text.Contains($marker) }).Count -gt 0
+        $inAspire = @($aspire | Where-Object { $_.text.Contains($marker) }).Count -gt 0
+        $dualOk = ($inInfra -and $inAspire)
+        if (-not $dualOk) {
+            $missing = if (-not $inInfra) { 'AddInfrastructure' } else { 'AddAspireInfrastructure' }
+            $dualFix = Pick-Fix ($(if (-not $inInfra) { $infra } else { $aspire }))
+            $dualNote = "marker '$marker' missing from $missing (R0.2a: register in BOTH paths)"
+        }
+        else { $dualNote = "marker '$marker' present in both registration paths" }
+    }
+    $ok = ($buildOk -and $dualOk)
+    $fixTarget = ''; $fixReason = ''
+    if (-not $buildOk) { $fixTarget = if ($primary) { $primary } elseif ($hostCsproj) { RelP $hostCsproj } else { '' }; $fixReason = 'build failed: ' + ((@($errors) | Select-Object -First 5) -join ' | ') }
+    elseif (-not $dualOk) { $fixTarget = $dualFix; $fixReason = $dualNote }
+    Write-Json ([ordered]@{ ok = $ok; ran = $ran; build_ok = $buildOk; errors = @($errors); primary_error_file = $primary;
+            dual_applicable = $dualApp; dual_registration_ok = $dualOk; dual_note = $dualNote; dual_fix_file = $dualFix;
+            fix_target = $fixTarget; fix_reason = $fixReason; can_fix = [bool]$fixTarget })
+}
+
+# ═════════════════ spec-anchored design pipeline (parity with bash) ═════════
+# Mirror of the design/build/analyze-slice/run/deploy/cr subcommands. The fence parsers
+# (extract/reconcile/paths) shell out to the SAME python3 as bash so the logic
+# is byte-identical; the rest is native. See .appweaver/DESIGN-FORMAT.md.
+# NOTE: authored for Windows parity; smoke-test under pwsh before relying on it.
+
+function Get-Py {
+    if (Get-Command python3 -ErrorAction SilentlyContinue) { return 'python3' }
+    if (Get-Command python  -ErrorAction SilentlyContinue) { return 'python' }
+    return $null
+}
+
+function Read-FeatureDir {
+    param([string]$RepoRoot)
+    $fj = Join-Path $RepoRoot '.appweaver/feature.json'
+    if (-not (Test-Path $fj)) { return '' }
+    try { return (Get-Content $fj -Raw | ConvertFrom-Json).feature_directory } catch { return '' }
+}
+
+function Resolve-FeatureDir {
+    param([string]$Arg, [string]$RepoRoot)
+    $fd = $Arg
+    if (-not $fd) { $fd = Read-FeatureDir -RepoRoot $RepoRoot }
+    if (-not $fd) { return $null }
+    if (-not [System.IO.Path]::IsPathRooted($fd)) { $fd = Join-Path $RepoRoot $fd }
+    return $fd
+}
+
+function Resolve-NamedTemplate {
+    param([string]$Name, [string]$RepoRoot)
+    $base = Join-Path $RepoRoot '.appweaver/templates'
+    $file = "$Name.md"
+    $override = Join-Path $base "overrides/$file"
+    if (Test-Path $override) { return $override }
+    $presets = Join-Path $RepoRoot '.appweaver/presets'
+    if (Test-Path $presets) {
+        $hit = Get-ChildItem -Directory $presets -ErrorAction SilentlyContinue |
+            ForEach-Object { Join-Path $_.FullName "templates/$file" } |
+            Where-Object { Test-Path $_ } | Select-Object -First 1
+        if ($hit) { return $hit }
+    }
+    $exts = Join-Path $RepoRoot '.appweaver/extensions'
+    if (Test-Path $exts) {
+        $hit = Get-ChildItem -Directory $exts -ErrorAction SilentlyContinue |
+            Where-Object { -not $_.Name.StartsWith('.') } |
+            ForEach-Object { Join-Path $_.FullName "templates/$file" } |
+            Where-Object { Test-Path $_ } | Select-Object -First 1
+        if ($hit) { return $hit }
+    }
+    $core = Join-Path $base $file
+    if (Test-Path $core) { return $core }
+    return $null
+}
+
+# The former path-tagged helpers (design-extract / -reconcile / -paths) are GONE, in
+# lockstep with the bash twin. They belonged to a retired four-document model in which
+# design.{domain,application,api,infra}.md carried the source inside ```lang path=…
+# fences. Nothing emits that fence any more, and their glob (`design.*.md`) could not
+# match a single `design.md` even if something did — so all three returned nothing,
+# silently, at exit 0. "Which files is this slice made of" is now an OKF query:
+# aw-xref concept-paths to read, concept-upsert --merge to write.
+function Invoke-DesignScaffold {
+    param([string[]]$Rest)
+    $fdArg = ''; $tplName = ''; $lane = 'service'
+    # --lane service|ui: WHOSE design this is. It selects a coherent (template,
+    # document) PAIR rather than two independent flags — service scaffolds
+    # design-template into design.md, ui scaffolds ui-design-template into
+    # design.ui.md — so no caller can write the service template under the UI lane's
+    # filename. Default `service` leaves every existing caller byte-identical.
+    # --template <name> overrides the TEMPLATE half only; the document name follows
+    # --lane. In a brownfield repo onboard GENERATES a code-derived override for both
+    # names, so the defaults already yield the as-built structure.
+    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] } { $_ -in '--lane','-Lane' } { $lane = $Rest[++$i] } { $_ -in '--template','-Template' } { $tplName = $Rest[++$i] } } }
+    switch ($lane) {
+        'service' { $docName = 'design.md';    if (-not $tplName) { $tplName = 'design-template' } }
+        'ui'      { $docName = 'design.ui.md'; if (-not $tplName) { $tplName = 'ui-design-template' } }
+        default   { Write-Error ("design-scaffold: unknown --lane '" + $lane + "' (service|ui)"); exit 1 }
+    }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'design-scaffold: no feature set (run /appweaver select-feature first) and no --feature-dir'; exit 1 }
+    New-Item -ItemType Directory -Force -Path $fd | Out-Null
+    $target = Join-Path $fd $docName
+    if (Test-Path $target) { $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 }
+        $created = $true
+    }
+    # override_active: is a PROJECT-level override installed for this template name?
+    # Computed ALWAYS (a stable signal on bootstrap AND delta). onboard installs the
+    # code-derived brownfield template as the `design-template` override, so
+    # override_active=true means the forward design phase should author brownfield.
+    $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; lane = $lane; created = $created; override_active = $overrideActive; template = $tplName; template_source = $tsOut })
+}
+
+# Read one field out of the lane model. Twin of the bash inline python readers: the
+# shells never parse stacks.json themselves, so its schema has one reader.
+function Get-LaneField {
+    param([string]$Field, [string]$Kind)
+    $py = Get-Py
+    if (-not $py) { return '' }
+    $core = Join-Path $PSScriptRoot '..' 'python' 'aw-stack.py'
+    if (-not (Test-Path $core)) { return '' }
+    $argsList = @('--repo', (Get-RepoRoot), 'resolve')
+    if ($Kind) { $argsList += @('--kind', $Kind) }
+    try {
+        $line = (& $py $core @argsList 2>$null | Select-Object -First 1)
+        if (-not $line) { return '' }
+        $v = ($line | ConvertFrom-Json).$Field
+        if ($null -eq $v) { return '' }
+        return [string]$v
+    } catch { return '' }
+}
+
+# Every ecosystem the declared lanes belong to, deduped and empty when nothing is
+# declared. This keys the stack-partitioned corpora under foundations/<ecosystem>/ —
+# a Java repo has no business being offered a .NET bundle, and the lane model already
+# knows which it is. Twin of the bash _aw_ecosystems.
+function Get-Ecosystems {
+    $out = @()
+    foreach ($k in @('backend_ecosystem', 'frontend_ecosystem')) {
+        $v = Get-LaneField -Field $k
+        if ($v -and ($out -notcontains $v)) { $out += $v }
+    }
+    # NOT comma-wrapped. Every call site already writes @(Get-Ecosystems), and the
+    # wrapper would make that a one-element array CONTAINING the array — which counts
+    # as 1, contains no ecosystem name, and matches nothing.
+    return $out
+}
+
+function Invoke-BuildCompile {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+
+    # A DECLARED lane model is the answer, and it is a better answer than the ladder
+    # below in exactly the case that matters: a repo with two lanes. The sniffer takes
+    # the first toolchain it finds and silently never builds the second, which reports
+    # green for a frontend that was never compiled.
+    if ((Get-LaneField -Field 'lane_count') -and (Get-LaneField -Field 'lane_count') -ne '0') {
+        Invoke-AwStackCore -Op 'run-phase' -Rest @('--phase', 'build')
+        return
+    }
+
+    # 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
+    if ($hasSln -or $hasCsproj) {
+        $tool = 'dotnet'
+        if (Get-Command dotnet -ErrorAction SilentlyContinue) {
+            $cmd = 'dotnet build --nologo'; $ran = $true
+            Push-Location $repo; try { $log = (dotnet build --nologo 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } finally { Pop-Location }
+        } else { $ok = $false }
+    } elseif ((Test-Path (Join-Path $repo 'package.json')) -and (Get-Command npm -ErrorAction SilentlyContinue)) {
+        $tool = 'npm'; $cmd = 'npm run build --if-present'; $ran = $true
+        Push-Location $repo; try { $log = (npm run build --if-present 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } finally { Pop-Location }
+    }
+    $tail = if ($log.Length -gt 1400) { $log.Substring($log.Length - 1400) } else { $log }
+    Write-Json ([ordered]@{ ok = $ok; tool = $tool; ran = $ran; cmd = $cmd; log_tail = $tail })
+}
+
+function Invoke-TestRun {
+    param([string[]]$Rest)
+    # --scope repo  (default): run the whole suite — the historic behaviour, every existing
+    #               caller is unaffected.
+    # --scope slice          : run ONLY the tests whose FullyQualifiedName contains the
+    #               feature's aggregate name (feature-dir basename) plus any --also referrer
+    #               names — the per-feature integrity scope. .NET only; npm/none ignore it
+    #               and run the full suite. (Kept byte-for-byte in step with the bash cmd_test_run.)
+    $featureDir = ''; $scope = 'repo'; $also = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--feature-dir','-FeatureDir' } { $featureDir = $Rest[++$i] }
+            { $_ -in '--scope','-Scope' }            { $scope = $Rest[++$i] }
+            { $_ -in '--also','-Also' }              { $also = $Rest[++$i] }
+        }
+    }
+    $repo = Get-RepoRoot
+
+    # For scope=slice, build the token set = feature aggregate name + --also referrers, each
+    # sanitised to an identifier (VSTest filter operators |&()!=~ are illegal) and de-duped.
+    # A surviving token becomes a `FullyQualifiedName~<tok>` clause; substring match is
+    # deliberate — it over-includes (safe for an integrity fence) rather than under-scoping.
+    $slices = @()
+    if ($scope -eq 'slice') {
+        $names = @()
+        if ($featureDir) { $names += (Split-Path -Leaf ($featureDir.TrimEnd('/','\'))) }
+        if ($also) { $names += ($also -split ',') }
+        foreach ($name in $names) {
+            $tok = ($name -replace '[^A-Za-z0-9._-]','')
+            if ($tok -notmatch '^[A-Za-z]') { continue }        # must start with a letter
+            if ($slices -notcontains $tok) { $slices += $tok }   # de-dup
+        }
+    }
+
+    $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
+    $dotnetPresent = ($hasSln -or $hasCsproj)
+
+    # A DECLARED lane model answers this the same way it answers build-compile, and for
+    # the same reason: the ladder below recognises .NET and npm-at-the-root, and reports
+    # `tool:"none" ran:false ok:true` for everything else. On a repo whose lane declares
+    # `./mvnw test` that is a suite which never ran scoring the integrity fence GREEN.
+    #
+    # scope=slice keeps the .NET path whenever a .NET toolchain is present, because
+    # VSTest's --filter is the only per-test selector any shipped profile has. Elsewhere a
+    # slice run delegates and widens to the lane's whole suite, which the fence tolerates
+    # by design, and reports scoped=false so fence_green comes from `ok`.
+    # (Kept in step with the bash cmd_test_run.)
+    $laneCount = Get-LaneField -Field 'lane_count'
+    $useLanes = $false
+    if ($laneCount -and $laneCount -ne '0') {
+        if ($scope -ne 'slice' -or -not $dotnetPresent) { $useLanes = $true }
+    }
+    if ($useLanes) {
+        $py = Get-Py
+        $core = Join-Path $PSScriptRoot '..' 'python' 'aw-stack.py'
+        $line = (& $py $core '--repo' $repo 'run-phase' '--phase' 'test' | Select-Object -First 1)
+        $d = if ($line) { $line | ConvertFrom-Json } else { $null }
+        $dLog = if ($d -and $d.log_tail) { [string]$d.log_tail } else { '' }
+        $dOk = [bool]($d -and $d.ok)
+        Write-Json ([ordered]@{
+            ok          = $dOk
+            tool        = $(if ($d -and $d.tool) { [string]$d.tool } else { 'lanes' })
+            ran         = [bool]($d -and $d.ran)
+            scope       = $scope
+            slices      = ($slices -join ' ')
+            scoped      = $false
+            matched     = ($dLog -match 'Total:\s*[1-9]')
+            fence_green = $dOk
+            cmd         = $(if ($d -and $d.cmd) { [string]$d.cmd } else { '' })
+            log_tail    = $dLog
+            lanes_run     = @(if ($d) { $d.lanes_run } else { @() })
+            lanes_skipped = @(if ($d) { $d.lanes_skipped } else { @() })
+        })
+        return
+    }
+
+    if ($dotnetPresent) {
+        $tool = 'dotnet'
+        if (Get-Command dotnet -ErrorAction SilentlyContinue) {
+            if ($scope -eq 'slice') {
+                if ($slices.Count -eq 0) {
+                    # scope=slice but nothing valid to filter on — fail loudly, never
+                    # silently fall back to a repo-wide run.
+                    $log = "scope=slice but no valid filter tokens from --feature-dir/--also`n"
+                    $ok = $false; $ran = $false; $cmd = '(no filter tokens)'
+                } else {
+                    $filter = ($slices | ForEach-Object { "FullyQualifiedName~$_" }) -join '|'
+                    $scoped = $true; $cmd = "dotnet test --nologo --filter `"$filter`""; $ran = $true
+                    Push-Location $repo; try { $log = (dotnet test --nologo --filter $filter 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } finally { Pop-Location }
+                }
+            } else {
+                $cmd = 'dotnet test --nologo'; $ran = $true
+                Push-Location $repo; try { $log = (dotnet test --nologo 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } finally { Pop-Location }
+            }
+        } else { $ok = $false }
+    } elseif ((Test-Path (Join-Path $repo 'package.json')) -and (Get-Command npm -ErrorAction SilentlyContinue)) {
+        $tool = 'npm'; $cmd = 'npm test'; $ran = $true
+        Push-Location $repo; try { $log = (npm test 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } finally { Pop-Location }
+    }
+
+    # matched = at least one test was actually selected + run. Read from the LOG, never the
+    # exit code: a .NET --filter that selects ZERO tests still EXITS 0, so trusting the exit
+    # code would report an empty scoped run as green (the vacuous-pass trap).
+    if ($log -match 'Total:\s*[1-9]') { $matched = $true }
+
+    # fence_green — a green that actually proves something ran.
+    #   scoped run → ok AND matched (guards the zero-match vacuous pass)
+    #   everything else (repo suite, npm, no test tool, the loud no-token fail) → ok.
+    if ($scoped) { $fenceGreen = ($ok -and $matched) } else { $fenceGreen = $ok }
+
+    $tail = if ($log.Length -gt 1400) { $log.Substring($log.Length - 1400) } else { $log }
+    Write-Json ([ordered]@{ ok = $ok; tool = $tool; ran = $ran; scope = $scope; slices = ($slices -join ' '); scoped = $scoped; matched = $matched; fence_green = $fenceGreen; cmd = $cmd; log_tail = $tail })
+}
+
+function Invoke-RunMigrate {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+
+    # A DECLARED migration command wins outright. Schema migration is the phase stacks
+    # answer most differently — Flyway, Liquibase, Alembic, Prisma, golang-migrate — and
+    # no sniffer can pick between tools that happily coexist in one repo. When a lane
+    # declares 'migrate' in .appweaver/stacks.json, that IS the answer and it runs in the
+    # lane's own working directory like every other phase command.
+    if ((Get-LaneField -Field 'backend_migrate') -or (Get-LaneField -Field 'frontend_migrate')) {
+        $py = Get-Py
+        $core = Join-Path $PSScriptRoot '..' 'python' 'aw-stack.py'
+        $line = (& $py $core '--repo' $repo 'run-phase' '--phase' 'migrate' | Select-Object -First 1)
+        $d = if ($line) { $line | ConvertFrom-Json } else { $null }
+        Write-Json ([ordered]@{
+            ok       = [bool]($d -and $d.ok)
+            tool     = 'lanes'
+            ran      = [bool]($d -and $d.ran)
+            cmd      = $(if ($d) { [string]$d.cmd } else { '' })
+            log_tail = $(if ($d) { [string]$d.log_tail } else { '' })
+            lanes_run = @(if ($d) { $d.lanes_run } else { @() })
+        })
+        return
+    }
+
+    # WHERE to look for the migration project. The service lane's declared source path
+    # when there is one, 'src' when there is not. Migrations belong to the backend lane
+    # by definition, so a repo whose service code sits in 'Legacy/App/' or 'backend/'
+    # gets searched where its code actually is instead of being told it has no .NET
+    # project at all.
+    $svcRoot = Get-LaneField -Field 'backend_root'
+    if (-not $svcRoot) { $svcRoot = 'src' }
+    $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
+    $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 }
+    }
+    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 |
+            Select-Object -First 1 -ExpandProperty FullName
+        if (-not $project) {
+            $project = Get-ChildItem -Path $svcDir -Filter '*.csproj' -Recurse -ErrorAction SilentlyContinue |
+                Where-Object { $_.FullName -notmatch 'AppHost|ServiceDefaults|\.Web\.|Tests' } |
+                Select-Object -First 1 -ExpandProperty FullName
+        }
+        if ($project) {
+            $tool = 'dotnet-ef'
+            $cmd = "dotnet ef database update --project $project --context ApplicationDbContext"
+            $ran = $true
+            Push-Location $repo
+            try {
+                $log = (dotnet ef database update --project $project --context ApplicationDbContext 2>&1 | Out-String)
+                $ok = ($LASTEXITCODE -eq 0)
+            } finally { Pop-Location }
+        } else {
+            $tool = 'dotnet-ef'; $cmd = 'dotnet ef database update'; $ran = $true
+            Push-Location $repo; try { $log = (dotnet ef database update 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } finally { Pop-Location }
+        }
+    }
+    $tail = if ($log.Length -gt 1400) { $log.Substring($log.Length - 1400) } else { $log }
+    Write-Json ([ordered]@{ ok = $ok; tool = $tool; ran = $ran; cmd = $cmd; log_tail = $tail })
+}
+
+function Invoke-DeployDispatch {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot; $cfg = Join-Path $repo '.appweaver/deploy.json'
+    $configured = $false; $ran = $false; $ok = $true; $cmd = ''; $log = ''
+    if (Test-Path $cfg) { try { $cmd = (Get-Content $cfg -Raw | ConvertFrom-Json).command } catch { $cmd = '' } }
+    if ($cmd) {
+        $configured = $true; $ran = $true
+        Push-Location $repo; try { $log = (Invoke-Expression $cmd 2>&1 | Out-String); $ok = ($LASTEXITCODE -eq 0) } catch { $ok = $false; $log = $_.ToString() } finally { Pop-Location }
+    }
+    $tail = if ($log.Length -gt 1400) { $log.Substring($log.Length - 1400) } else { $log }
+    Write-Json ([ordered]@{ ok = $ok; configured = $configured; ran = $ran; cmd = $cmd; log_tail = $tail })
+}
+
+function Invoke-CrSetup {
+    param([string[]]$Rest)
+    $crId = ''; $fdArg = ''; $title = ''; $force = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--cr-id','-CrId' } { $crId = $Rest[++$i] }
+            { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] }
+            { $_ -in '--title','-Title' } { $title = $Rest[++$i] }
+            { $_ -in '--force','-Force' } { $force = '1' }
+        }
+    }
+    if (-not $crId) { $crId = 'CR-' + (Get-Date -Format 'yyyyMMdd-HHmmss') }
+    $repo = Get-RepoRoot; $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'cr-setup: no feature set and no --feature-dir'; exit 1 }
+    # Single-active-change guard: open the change FIRST so a second concurrent CR on the
+    # same aggregate is refused BEFORE any changes/<cr>/ dir is scaffolded (no orphan
+    # left behind). Re-opening the same cr_id is a no-op. --force overrides.
+    $avOpen = Invoke-ActiveVersion -FeatureDir $fd -Op 'open' -CrId $crId -Force $force
+    if ($LASTEXITCODE -and $LASTEXITCODE -ne 0) {
+        Write-Error "cr-setup: refusing to open '$crId' — a change is already open on this feature; finish it (finalize-delta -> analyze-slice -> close-delta) first, or pass --force."
+        $avOpen
+        exit 1
+    }
+    $crDir = Join-Path $fd "changes/$crId"
+    New-Item -ItemType Directory -Force -Path $crDir | Out-Null
+    $dspec = Join-Path $crDir 'delta-spec.md'; $ddesign = Join-Path $crDir 'delta-design.md'; $created = $false
+    if (-not (Test-Path $dspec)) { $t = Resolve-NamedTemplate -Name 'delta-spec-template' -RepoRoot $repo; if ($t) { Copy-Item $t $dspec } else { New-Item -ItemType File -Force -Path $dspec | Out-Null }; $created = $true }
+    if (-not (Test-Path $ddesign)) { $t = Resolve-NamedTemplate -Name 'delta-design-template' -RepoRoot $repo; if ($t) { Copy-Item $t $ddesign } else { New-Item -ItemType File -Force -Path $ddesign | Out-Null }; $created = $true }
+    Write-Json ([ordered]@{ cr_id = $crId; cr_dir = $crDir; delta_spec = $dspec; delta_design = $ddesign; title = $title; created = $created })
+}
+
+function Invoke-CrArchive {
+    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] }
+        }
+    }
+    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 }
+    $crDir = Join-Path $fd "changes/$crId"; $archRoot = Join-Path $fd 'changes/archive'; $archived = ''
+    if (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 }
+        Move-Item $crDir $dest; $archived = $dest
+    }
+    # Close the change in active_version.json (single version source): bump + clear.
+    $av = Invoke-ActiveVersion -FeatureDir $fd -Op 'close' | ConvertFrom-Json
+    Write-Json ([ordered]@{ ok = $true; archived_dir = $archived; version = $av.version; previous = $av.previous; closed_change = $av.closed_change })
+}
+
+# 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
+# number (spec.md, design.md, active_version.json) move in ONE stage by ONE
+# mechanism. Before this, design.md's header was bumped by the MODEL at
+# finalize-delta — a stage early, and guessing the target since the number was
+# never passed into the merge prompt — while spec.md's header was bumped by
+# nobody at all and sat at v1.0 forever.
+# Idempotent: re-stamping the same version reports `unchanged`, writes nothing.
+# Only the value moves; any trailing inline comment on the header line is kept.
+function Invoke-VersionStamp {
+    param([string[]]$Rest)
+    $ver = ''; $fdArg = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            { $_ -in '--version','-Version' } { $ver = $Rest[++$i] }
+            { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] }
+        }
+    }
+    if (-not $ver) { Write-Error 'version-stamp: --version required'; exit 1 }
+    $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()
+    [string[]]$stamped = @(); [string[]]$unchanged = @(); [string[]]$missing = @(); [string[]]$noHeader = @()
+    # First `**Version**: <value>` line only — that is the header. The Change History
+    # table's `| Version |` column head does not match this pattern.
+    # design.ui.md joins the spine where the feature has a UI half: the masters move in
+    # LOCKSTEP, so a document left behind at the old number is the one lie the version
+    # spine cannot tolerate. A feature without one reports it `missing` and nothing fails.
+    foreach ($name in @('spec.md', 'design.md', 'design.ui.md')) {
+        $p = Join-Path $fd $name
+        if (-not (Test-Path $p)) { $missing += $name; continue }
+        $src = Get-Content -Raw -Encoding UTF8 $p
+        $m = [regex]::Match($src, '(?m)^(\*\*Version\*\*:[ \t]*)(\S+)(.*)$')
+        if (-not $m.Success) { $noHeader += $name; continue }
+        if ($m.Groups[2].Value -eq $ver) { $unchanged += $name; continue }
+        $out = $src.Substring(0, $m.Index) + $m.Groups[1].Value + $ver + $m.Groups[3].Value +
+               $src.Substring($m.Index + $m.Length)
+        [System.IO.File]::WriteAllText($p, $out)
+        $stamped += $name
+    }
+    Write-Json ([ordered]@{ ok = $true; version = $ver; stamped = $stamped; unchanged = $unchanged;
+                            missing = $missing; no_header = $noHeader; count = $stamped.Count })
+}
+
+# ─────────────────────────────── main ──────────────────────────────────────
+if ($args.Count -lt 1) { Write-Output 'Usage: aw-spec-actions.ps1 <subcommand> [options]'; exit 0 }
+$sub = $args[0]
+$rest = @(); if ($args.Count -gt 1) { $rest = $args[1..($args.Count - 1)] }
+
+switch ($sub) {
+    'resolve-domain'   { Invoke-ResolveDomain   -Rest $rest }
+    'resolve-tech'     { Invoke-ResolveTech     -Rest $rest }
+    'scaffold'         { Invoke-Scaffold         -Rest $rest }
+    'resolve-hooks'    { Invoke-ResolveHooks     -Rest $rest }
+    'create-checklist' { Invoke-CreateChecklist  -Rest $rest }
+    'list-domains'     { Invoke-ListDomains      -Rest $rest }
+    'set-domain'       { Invoke-SetDomain        -Rest $rest }
+    'stack-list'       { Invoke-StackList        -Rest $rest }
+    'stack-detect'     { Invoke-StackDetect      -Rest $rest }
+    'lane-declare'     { Invoke-LaneDeclare      -Rest $rest }
+    'lane-resolve'     { Invoke-LaneResolve      -Rest $rest }
+    'lane-verify'      { Invoke-LaneVerify       -Rest $rest }
+    'lane-probe'       { Invoke-LaneProbe        -Rest $rest }
+    'list-features'    { Invoke-ListFeatures     -Rest $rest }
+    'set-feature'      { Invoke-SetFeature       -Rest $rest }
+    'version-read'     { Invoke-VersionState 'read'  $rest }
+    'version-init'     { Invoke-VersionState 'init'  $rest }
+    'feature-paths'    { Invoke-FeaturePaths     -Rest $rest }
+    'design-scaffold'  { Invoke-DesignScaffold   -Rest $rest }
+    'build-compile'    { Invoke-BuildCompile     -Rest $rest }
+    'test-run'         { Invoke-TestRun          -Rest $rest }
+    'run-migrate'      { Invoke-RunMigrate       -Rest $rest }
+    'deploy-dispatch'  { Invoke-DeployDispatch   -Rest $rest }
+    'cr-setup'         { Invoke-CrSetup          -Rest $rest }
+    'cr-archive'       { Invoke-CrArchive        -Rest $rest }
+    'version-stamp'    { Invoke-VersionStamp     -Rest $rest }
+    'checklist-read'   { Invoke-ChecklistRead    -Rest $rest }
+    'checklist-apply'  { Invoke-ChecklistApply   -Rest $rest }
+    'detect-project'   { Invoke-DetectProject    -Rest $rest }
+    'foundation-list'  { Invoke-FoundationList   -Rest $rest }
+    'foundation-locate' { Invoke-FoundationLocate -Rest $rest }
+    'foundation-unpack' { Invoke-FoundationUnpack -Rest $rest }
+    'foundation-verify' { Invoke-FoundationVerify -Rest $rest }
+    'foundation-stash-dbcontext' { Invoke-FoundationStashDbContext -Rest $rest }
+    'list-components'  { Invoke-ListComponents   -Rest $rest }
+    'component-catalog' { Invoke-ComponentCatalog -Rest $rest }
+    'component-verify' { Invoke-ComponentVerify   -Rest $rest }
+    'find-host-project' { Invoke-FindHostProject  -Rest $rest }
+    'setup-constitution' { Invoke-SetupConstitution -Rest $rest }
+    'compose-constitution' { Invoke-ComposeConstitution -Rest $rest }
+    'constitution-verify' { Invoke-ConstitutionVerify -Rest $rest }
+    'agent-context-update' { Invoke-AgentContextUpdate -Rest $rest }
+    default            { Write-Error "Unknown subcommand: $sub"; exit 1 }
+}