aw-spec-cli 0.1.4 → 0.1.5

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

@@ -0,0 +1,1563 @@
+#!/usr/bin/env pwsh
+#
+# aw-spec-actions.ps1 — common action dispatcher for declarative aw-spec skills
+# (Windows / PowerShell mirror of aw-spec-actions.sh).
+#
+# ONE shared script for every integration (.claude / .agents / .kilocode). The
+# declarative skill.yaml files reference these subcommands via `execute_script`.
+# 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 (the skill's single `llm_generate` step).
+#
+# 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 '.aw-spec')) { 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 '.aw-spec/templates'
+    $name = 'spec-template.md'
+    $override = Join-Path $base "overrides/$name"
+    if (Test-Path $override) { return $override }
+    $presets = Join-Path $RepoRoot '.aw-spec/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 '.aw-spec/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 '.aw-spec/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 "docs/domainspecs/$domain/comandrulemap.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
+# docs/domainspecs/<domain>/commandtechrulemap.md. The technical rule files (the
+# docs/architecture · docs/security · docs/interop · docs/governance set formerly
+# hardcoded in each workflow's `standards:` block) are configured per-command here.
+# The technical CONSTITUTION (constitution.technical.md) is NOT mapped — each
+# consumer still refers to it directly, as-is.
+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 '.aw-spec/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 "docs/domainspecs/$domain/commandtechrulemap.md"
+    $techmapExists = ($domain -ne '') -and (Test-Path $techmap)
+
+    $candidates = @()
+    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) { $candidates = $found; break }
+        }
+    }
+
+    Write-Json ([ordered]@{
+        domain             = $domain
+        techrulemap_exists = $techmapExists
+        candidates         = @($candidates)
+    })
+}
+
+# ─────────────────────────── 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 '.aw-spec/feature.json'
+    New-Item -ItemType Directory -Force -Path (Join-Path $repo '.aw-spec') | 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 '.aw-spec/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
+
+## Merge Readiness
+
+- [ ] Header is complete: aggregate, change type, base version
+- [ ] Impact lists the affected ids (FR / BR / CN / DC / IC / 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
+  /aw-spec-orch analyze-delta-design.
+- Items marked incomplete require delta-spec updates before /aw-spec-orch 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
+
+## 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 /aw-spec-orch design
+"@ }
+    Set-Content -Path $checklistFile -Value $content -Encoding UTF8
+    Write-Json ([ordered]@{ checklist_file = $checklistFile; kind = $kind; target = $targetFile; created = $created })
+}
+
+# ─────────────────────────── list-domains ──────────────────────────────────
+function Invoke-ListDomains {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $base = Join-Path $repo 'docs/domainspecs'
+    $domains = @()
+    if (Test-Path $base) {
+        $domains = @(Get-ChildItem -Directory $base -ErrorAction SilentlyContinue | 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 = "docs/domainspecs/$domain/comandrulemap.md"
+    $mapExists = Test-Path (Join-Path $repo $mapRel)
+
+    New-Item -ItemType Directory -Force -Path (Join-Path $repo '.aw-spec') | Out-Null
+    @{ domain = $domain } | ConvertTo-Json -Compress |
+        Set-Content -Path (Join-Path $repo '.aw-spec/domain.json') -Encoding UTF8
+
+    Write-Json ([ordered]@{
+        domain     = $domain
+        map_path   = $mapRel
+        map_exists = $mapExists
+        written    = $true
+    })
+}
+
+# ─────────────────────────── 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 '.aw-spec') | Out-Null
+    @{ feature_directory = $featureDirRel } | ConvertTo-Json -Compress |
+        Set-Content -Path (Join-Path $repo '.aw-spec/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 '.aw-spec/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 /aw-spec-orch 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 two-document model: spec.md + design.md ONLY. plan.md / tasks.md belonged to
+    # the retired /aw-spec-plan + /aw-spec-tasks phases and had zero consumers.
+    $spec = Join-Path $fd 'spec.md'
+    $design = Join-Path $fd 'design.md'
+    Write-Json ([ordered]@{
+        feature       = $feature
+        feature_dir   = $fd
+        spec_file     = $spec
+        design_file   = $design
+        spec_exists   = (Test-Path $spec)
+        design_exists = (Test-Path $design)
+    })
+}
+
+# ────────────────────────── 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 ────────────────────────────
+function Invoke-DetectProject {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $markers = @()
+    $prune = @('.aw-spec', 'docs', 'specs', '.git', 'node_modules')
+    Get-ChildItem -Path $repo -Recurse -File -Include *.sln, *.csproj -ErrorAction SilentlyContinue |
+        Where-Object { $rel = $_.FullName.Substring($repo.Length).TrimStart('\','/'); -not ($prune | Where-Object { $rel -like "$_*" -or $rel -like "$_/*" -or $rel -like "$_\*" }) } |
+        Select-Object -First 20 | ForEach-Object { $markers += ($_.FullName.Substring($repo.Length).TrimStart('\','/') -replace '\\','/') }
+    foreach ($f in @('package.json','pom.xml','build.gradle','build.gradle.kts','go.mod','Cargo.toml','pyproject.toml')) {
+        if (Test-Path (Join-Path $repo $f)) { $markers += $f }
+    }
+    Write-Json ([ordered]@{ scaffolded = ($markers.Count -gt 0); markers = @($markers) })
+}
+
+
+# ─────────────────────────── foundation-locate ─────────────────────────────
+# ──────────────────────────── foundation-list ──────────────────────────────
+# List available foundations (docs/<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
+    $foundations = @()
+    $docs = Join-Path $repo 'docs'
+    if (Test-Path $docs) {
+        foreach ($d in (Get-ChildItem -Directory $docs -ErrorAction SilentlyContinue)) {
+            if (Test-Path (Join-Path $d.FullName "$($d.Name).pack.txt")) { $foundations += $d.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
+        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
+    $available = @()
+    $docs = Join-Path $repo 'docs'
+    if (Test-Path $docs) {
+        foreach ($d in (Get-ChildItem -Directory $docs -ErrorAction SilentlyContinue)) {
+            if (Get-ChildItem $d.FullName -Filter *.pack.txt -ErrorAction SilentlyContinue | Select-Object -First 1) { $available += $d.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 }
+    $fdir = Join-Path $repo "docs/$name"
+    if (-not (Test-Path $fdir)) { _fail "Foundation '$name' not found (expected docs/$name/)"; return }
+    $pack = Join-Path $fdir "$name.pack.txt"
+    if (-not (Test-Path $pack)) { _fail "Foundation '$name' has no bundle yet (expected $pack). Build it via docs/$name/PACKAGING.md."; return }
+    $runner = ''; $unpacker = ''
+    if ((Get-Command pwsh -ErrorAction SilentlyContinue) -and (Test-Path (Join-Path $fdir 'unpack-foundation.ps1'))) { $runner = 'pwsh'; $unpacker = "docs/$name/unpack-foundation.ps1" }
+    elseif (Test-Path (Join-Path $fdir 'unpack-foundation.sh')) { $runner = 'sh'; $unpacker = "docs/$name/unpack-foundation.sh" }
+    else { _fail "No unpacker found in docs/$name/ (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; app = $app; out_dir = $out
+        pack_file = "docs/$name/$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
+    $fdir = Join-Path $repo "docs/$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|docs|\.aw-spec|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):
+#   .aw-spec/memory/constitution.technical.md  (from constitution-technical-template)
+#   .aw-spec/memory/constitution.domain.md     (from constitution-domain-template)
+# The composed constitution.md is produced by compose-constitution after authoring.
+function Invoke-SetupConstitution {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    New-Item -ItemType Directory -Force -Path (Join-Path $repo '.aw-spec/memory') | Out-Null
+    $base = Join-Path $repo '.aw-spec/templates'
+    $tech = Join-Path $repo '.aw-spec/memory/constitution.technical.md'
+    $dom  = Join-Path $repo '.aw-spec/memory/constitution.domain.md'
+    $techCreated = $false; $domCreated = $false
+    if (-not (Test-Path $tech)) {
+        $tpl = $null
+        $ov = Join-Path $base 'overrides/constitution-technical-template.md'; $core = Join-Path $base 'constitution-technical-template.md'
+        if (Test-Path $ov) { $tpl = $ov } elseif (Test-Path $core) { $tpl = $core }
+        if ($tpl) { Copy-Item $tpl $tech } else { New-Item -ItemType File -Force -Path $tech | Out-Null }
+        $techCreated = $true
+    }
+    if (-not (Test-Path $dom)) {
+        $tpl = $null
+        $ov = Join-Path $base 'overrides/constitution-domain-template.md'; $core = Join-Path $base 'constitution-domain-template.md'
+        if (Test-Path $ov) { $tpl = $ov } elseif (Test-Path $core) { $tpl = $core }
+        if ($tpl) { Copy-Item $tpl $dom } else { New-Item -ItemType File -Force -Path $dom | Out-Null }
+        $domCreated = $true
+    }
+    Write-Json ([ordered]@{ constitution_technical_file = $tech; constitution_domain_file = $dom; technical_created = $techCreated; domain_created = $domCreated })
+}
+
+# ─────────────────────────────── compose-constitution ──────────────────────
+# Deterministically concatenate the technical + domain halves into the composed
+# constitution.md (human/compat view; NOT loaded by the pipeline phases). If the
+# domain half is absent/empty, the composed file mirrors the technical half.
+function Invoke-ComposeConstitution {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $tech = Join-Path $repo '.aw-spec/memory/constitution.technical.md'
+    $dom  = Join-Path $repo '.aw-spec/memory/constitution.domain.md'
+    $out  = Join-Path $repo '.aw-spec/memory/constitution.md'
+    if (-not (Test-Path $tech)) {
+        Write-Json ([ordered]@{ composed_file = $out; ok = $false; domain_included = $false; issues = @('technical half not found') }); return
+    }
+    $header = @(
+        '<!-- COMPOSED — generated by `aw-spec-actions compose-constitution`. Do not edit here.',
+        '     Source of truth: constitution.technical.md + constitution.domain.md (edit those).',
+        '     Pipeline phases load the halves directly; this composed view is for humans/compat. -->',
+        ''
+    ) -join "`n"
+    $body = $header + "`n" + (Get-Content -Raw $tech)
+    # Include the domain half only if authored — non-empty AND free of residual
+    # [ALL_CAPS] template placeholders (a technical-only project leaves it a raw template).
+    $includeDomain = $false
+    if ((Test-Path $dom) -and ((Get-Item $dom).Length -gt 0)) {
+        if (-not (Select-String -Path $dom -Pattern '\[[A-Z0-9]+(_[A-Z0-9]+)+\]' -Quiet)) { $includeDomain = $true }
+    }
+    if ($includeDomain) {
+        $body += "`n`n---`n`n" + (Get-Content -Raw $dom)
+    }
+    Set-Content -Path $out -Value $body -NoNewline
+    Write-Json ([ordered]@{ composed_file = $out; ok = $true; domain_included = $includeDomain; issues = @() })
+}
+
+# ─────────────────────────── constitution-verify ───────────────────────────
+# Deterministic lint of a generated constitution (NO LLM): residual
+# [ALL_CAPS_WITH_UNDERSCORE] placeholder tokens, 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.
+function Get-LastLabeledVersion {
+    param([string]$Text)
+    $m = [regex]::Match($Text, '(?im)version[^0-9\n]{0,20}v?(\d+\.\d+\.\d+)')
+    if ($m.Success) { return $m.Groups[1].Value } else { return $null }
+}
+function Invoke-ConstitutionVerify {
+    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 '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
+    }
+    $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. Residual ALL_CAPS_WITH_UNDERSCORE placeholder tokens.
+    $placeholders = @([regex]::Matches($body, '\[([A-Z0-9]+(?:_[A-Z0-9]+)+)\]') |
+        ForEach-Object { $_.Groups[1].Value } | Select-Object -Unique | Sort-Object)
+    # 2. Version: labeled body version vs the report's "new" version.
+    $versionBody = Get-LastLabeledVersion $body
+    $arrow = [regex]::Match($report, '(\d+\.\d+\.\d+)\s*(?:->|→|=>)\s*(\d+\.\d+\.\d+)')
+    $versionReport = if ($arrow.Success) { $arrow.Groups[2].Value } else { Get-LastLabeledVersion $report }
+    $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 ', ')) }
+    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); 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 '.aw-spec/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 ───────────────────────────
+function Invoke-ListComponents {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $base = Join-Path $repo 'docs/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) })
+}
+
+# ─────────────────────────────── find-host-project ─────────────────────────
+function Invoke-FindHostProject {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $prog = Get-ChildItem -Path (Join-Path $repo 'src') -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|docs|specs|\.aw-spec|obj|bin)[/\\]' } |
+            Select-Object -First 1 -ExpandProperty FullName
+    }
+    if (-not $prog) { Write-Json ([ordered]@{ found = $false; program_cs = ''; project_dir = ''; csproj = '' }); 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 { '' }) })
+}
+
+# ─────────────────────────────── component-catalog ──────────────────────────
+# Deterministic parse of a component's integration.md "Implementation catalog"
+# markdown table (NO LLM). Returns {integrable, impl_keys[], implementations[{key,desc}]}.
+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 }
+    $repo = Get-RepoRoot
+    if (-not [System.IO.Path]::IsPathRooted($file)) { $file = Join-Path $repo $file }
+    if (-not (Test-Path $file)) { Write-Json ([ordered]@{ integrable = $false; impl_keys = @(); implementations = @() }); return }
+    $lines = Get-Content $file
+    $start = -1
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        if ($lines[$i] -match '^#{1,6}\s' -and $lines[$i] -match '(?i)implementation catalog|selection list') { $start = $i + 1; break }
+    }
+    $rows = @()
+    if ($start -ge 0) {
+        for ($i = $start; $i -lt $lines.Count; $i++) {
+            $ln = [string]$lines[$i]
+            if ($ln -match '^#{1,6}\s') { break }
+            $s = $ln.Trim()
+            if ($s.StartsWith('|')) { $rows += $s }
+            elseif ($rows.Count -gt 0) { break }
+        }
+    }
+    function Split-Cells([string]$row) { return ($row.Trim().Trim('|') -split '\|') | ForEach-Object { $_.Trim() } }
+    $implKeys = @(); $impls = @()
+    if ($rows.Count -ge 2) {
+        $header = @(Split-Cells $rows[0])
+        $kidx = 0
+        for ($j = 0; $j -lt $header.Count; $j++) { if ($header[$j].ToLower() -eq 'key') { $kidx = $j; break } }
+        for ($r = 2; $r -lt $rows.Count; $r++) {
+            $c = @(Split-Cells $rows[$r])
+            $isSep = $true; foreach ($x in $c) { if ($x -notmatch '^:?-{2,}:?$') { $isSep = $false; break } }
+            if ($isSep) { continue }
+            if ($kidx -ge $c.Count) { continue }
+            $key = $c[$kidx].Trim('`').Trim()
+            if (-not $key) { continue }
+            $parts = @()
+            for ($j = 0; $j -lt $c.Count; $j++) {
+                if ($j -eq $kidx -or -not $c[$j]) { continue }
+                $h = if ($j -lt $header.Count) { $header[$j] } else { '' }
+                $parts += if ($h) { "{0}: {1}" -f $h, $c[$j] } else { $c[$j] }
+            }
+            $implKeys += $key
+            $impls += [ordered]@{ key = $key; desc = ($parts -join ' · ') }
+        }
+    }
+    Write-Json ([ordered]@{ integrable = ($implKeys.Count -gt 0); impl_keys = @($implKeys); implementations = @($impls) })
+}
+
+# ─────────────────────────────── 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 .aw-spec/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 '.aw-spec/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 '.aw-spec/templates'
+    $file = "$Name.md"
+    $override = Join-Path $base "overrides/$file"
+    if (Test-Path $override) { return $override }
+    $presets = Join-Path $RepoRoot '.aw-spec/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 '.aw-spec/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 = 'design-template'
+    # --template <name>: which template to scaffold (default `design-template`).
+    # In a brownfield repo, /aw-spec-orch onboard GENERATES a code-derived
+    # `design-template` override, so the default already yields the as-built structure
+    # for both forward `design` and adopt (no per-call --template needed).
+    for ($i = 0; $i -lt $Rest.Count; $i++) { switch ($Rest[$i]) { { $_ -in '--feature-dir','-FeatureDir' } { $fdArg = $Rest[++$i] } { $_ -in '--template','-Template' } { $tplName = $Rest[++$i] } } }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'design-scaffold: no feature set (run /aw-spec-orch select-feature first) and no --feature-dir'; exit 1 }
+    New-Item -ItemType Directory -Force -Path $fd | Out-Null
+    $target = Join-Path $fd 'design.md'
+    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 (".aw-spec/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; created = $created; override_active = $overrideActive; template = $tplName; template_source = $tsOut })
+}
+
+function Invoke-BuildCompile {
+    param([string[]]$Rest)
+    $repo = Get-RepoRoot
+    $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
+    if ($hasSln -or $hasCsproj) {
+        $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
+    $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
+    $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 src/.
+        $project = Get-ChildItem -Path (Join-Path $repo 'src') -Filter '*.Service.csproj' -Recurse -ErrorAction SilentlyContinue |
+            Select-Object -First 1 -ExpandProperty FullName
+        if (-not $project) {
+            $project = Get-ChildItem -Path (Join-Path $repo 'src') -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 '.aw-spec/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.
+    foreach ($name in @('spec.md', 'design.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 }
+    '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 }
+}