specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/scripts/powershell/check-prerequisites.ps1

@@ -0,0 +1,148 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Consolidated prerequisite checking for the Spec-Driven Development workflow.
+.DESCRIPTION
+    Contract-equivalent to `scripts/bash/check-prerequisites.sh`: the same options, the
+    same two output modes, and the same exit codes.
+
+    ⚠️ Arguments are parsed with a manual loop rather than a `param()` block, and that
+    is deliberate: callers are command documents that invoke the Bash side as
+    `check-prerequisites.sh --json`, and a `param()` block would reject `--json`
+    (PowerShell binds `-Json`). Accepting both spellings keeps one call site valid on
+    both platforms — the alternative is two call conventions that will drift.
+
+.EXAMPLE
+    ./check-prerequisites.ps1 --json --require-tasks --include-tasks
+    ./check-prerequisites.ps1 --paths-only
+#>
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+. (Join-Path $PSScriptRoot 'common.ps1')
+
+$jsonMode = $false
+$requireTasks = $false
+$includeTasks = $false
+$pathsOnly = $false
+
+foreach ($arg in $args) {
+    switch -Regex ($arg) {
+        '^--?json$'          { $jsonMode = $true; continue }
+        '^--?require-tasks$' { $requireTasks = $true; continue }
+        '^--?include-tasks$' { $includeTasks = $true; continue }
+        '^--?paths-only$'    { $pathsOnly = $true; continue }
+        '^--?help$|^-h$' {
+            # ⚠️ Reproduces the Bash help text byte-for-byte EXCEPT the script's own
+            # name: a usage message that named the other platform's script would send
+            # the reader looking for a file that is not there. Script name is the ONE
+            # intentional difference; the `  ` (two-space) lines below are not blanks
+            # by accident — they are what the Bash heredoc emits.
+            @'
+Usage: check-prerequisites.ps1 [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.ps1 --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.ps1 --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.ps1 --paths-only
+  
+'@ | Write-Output
+            exit 0
+        }
+        default {
+            [Console]::Error.WriteLine("ERROR: Unknown option '$arg'. Use --help for usage information.")
+            exit 1
+        }
+    }
+}
+
+$paths = Get-FeaturePaths
+$featureDir = $paths.FEATURE_DIR
+$implPlan = $paths.IMPL_PLAN
+$featureSpec = $paths.FEATURE_SPEC
+$tasks = $paths.TASKS
+
+# --- paths-only: emit and exit (no validation) ----------------------------------------
+if ($pathsOnly) {
+    if ($jsonMode) {
+        # Minimal JSON paths payload. Hand-built to keep the key order and the exact
+        # byte shape the Bash side prints.
+        # ⚠️ Literal braces in a `-f` format string MUST be doubled: a bare `{` opens a
+        # format item. The Bash side needs no escape, which is why the two expressions
+        # look alike and are not — the parity check is what catches a missed doubling.
+        $json = '{{"REPO_ROOT":"{0}","BRANCH":"{1}","FEATURE_SCOPE":"{2}","FEATURE_DIR":"{3}","FEATURE_SPEC":"{4}","IMPL_PLAN":"{5}","TASKS":"{6}"}}' -f `
+            $paths.REPO_ROOT, $paths.CURRENT_BRANCH, $paths.FEATURE_SCOPE, $paths.FEATURE_DIR, $paths.FEATURE_SPEC, $paths.IMPL_PLAN, $paths.TASKS
+        Write-Output $json
+    } else {
+        Write-Output "REPO_ROOT: $($paths.REPO_ROOT)"
+        Write-Output "BRANCH: $($paths.CURRENT_BRANCH)"
+        Write-Output "FEATURE_SCOPE: $($paths.FEATURE_SCOPE)"
+        Write-Output "FEATURE_DIR: $($paths.FEATURE_DIR)"
+        Write-Output "FEATURE_SPEC: $($paths.FEATURE_SPEC)"
+        Write-Output "IMPL_PLAN: $($paths.IMPL_PLAN)"
+        Write-Output "TASKS: $($paths.TASKS)"
+    }
+    exit 0
+}
+
+# --- validation ------------------------------------------------------------------------
+if (-not (Test-Path -LiteralPath $featureDir -PathType Container)) {
+    [Console]::Error.WriteLine("ERROR: Feature directory not found: $featureDir")
+    [Console]::Error.WriteLine('Run /specpro-specify first to create the feature structure.')
+    exit 1
+}
+
+if (-not (Test-Path -LiteralPath $implPlan -PathType Leaf)) {
+    [Console]::Error.WriteLine("ERROR: plan.md not found in $featureDir")
+    [Console]::Error.WriteLine('Run /specpro-plan first to create the implementation plan.')
+    exit 1
+}
+
+if ($requireTasks -and -not (Test-Path -LiteralPath $tasks -PathType Leaf)) {
+    [Console]::Error.WriteLine("ERROR: tasks.md not found in $featureDir")
+    [Console]::Error.WriteLine('Run /specpro-tasks first to create the task list.')
+    exit 1
+}
+
+# --- available documents ---------------------------------------------------------------
+$docs = [System.Collections.Generic.List[string]]::new()
+if (Test-Path -LiteralPath $featureSpec -PathType Leaf) { $docs.Add('spec.md') }
+if (Test-Path -LiteralPath $paths.RESEARCH -PathType Leaf) { $docs.Add('research.md') }
+if (Test-Path -LiteralPath $paths.DATA_MODEL -PathType Leaf) { $docs.Add('data-model.md') }
+if ((Test-Path -LiteralPath $paths.CONTRACTS_DIR -PathType Container) -and
+    ((Get-ChildItem -LiteralPath $paths.CONTRACTS_DIR -Force | Measure-Object).Count -gt 0)) {
+    $docs.Add('contracts/')
+}
+if (Test-Path -LiteralPath $paths.QUICKSTART -PathType Leaf) { $docs.Add('quickstart.md') }
+if ($includeTasks -and (Test-Path -LiteralPath $tasks -PathType Leaf)) { $docs.Add('tasks.md') }
+# Optional high-level test plan — never required.
+if (Test-Path -LiteralPath $paths.TEST_TASKS -PathType Leaf) { $docs.Add('test-tasks.md') }
+
+if ($jsonMode) {
+    $jsonDocs = '[' + (($docs | ForEach-Object { '"' + $_ + '"' }) -join ',') + ']'
+    Write-Output ('{{"FEATURE_DIR":"{0}","FEATURE_SCOPE":"{1}","AVAILABLE_DOCS":{2}}}' -f $featureDir, $paths.FEATURE_SCOPE, $jsonDocs)
+} else {
+    Write-Output "FEATURE_DIR:$featureDir"
+    Write-Output 'AVAILABLE_DOCS:'
+    Write-CheckFile $featureSpec 'spec.md'
+    Write-CheckFile $paths.RESEARCH 'research.md'
+    Write-CheckFile $paths.DATA_MODEL 'data-model.md'
+    Write-CheckDir $paths.CONTRACTS_DIR 'contracts/'
+    Write-CheckFile $paths.QUICKSTART 'quickstart.md'
+    if ($includeTasks) { Write-CheckFile $tasks 'tasks.md' }
+    Write-CheckFile $paths.TEST_TASKS 'test-tasks.md'
+}

specpro_cli/assets/scripts/powershell/common.ps1

@@ -0,0 +1,95 @@
+# Common functions for all specpro support scripts (PowerShell).
+#
+# Contract-equivalent to `scripts/bash/common.sh`. "Contract" here means what callers
+# depend on: the same three queries, the same returned path set, and the same fallbacks
+# — NOT the same function names (PowerShell casing is the convention on this side) and
+# not the same implementation.
+#
+# Dot-source this file; it defines functions and has no side effects.
+
+Set-StrictMode -Version Latest
+
+# Repository root, with a fallback for non-git repositories.
+function Get-RepoRoot {
+    if (Test-HasGit) {
+        # `git rev-parse --show-toplevel` already returns an absolute, forward-slash path.
+        $root = & git rev-parse --show-toplevel 2>$null
+        if ($LASTEXITCODE -eq 0 -and $root) { return $root.Trim() }
+    }
+    # Fall back to the script location: <repo>/scripts/powershell/common.ps1 -> <repo>
+    return (Resolve-Path (Join-Path $PSScriptRoot '..' '..')).Path
+}
+
+# Current branch — informational only. Branch information is NOT used for directory
+# structure; every spec file lives directly under specs/.
+function Get-CurrentBranch {
+    if (Test-HasGit) {
+        $branch = & git rev-parse --abbrev-ref HEAD 2>$null
+        if ($LASTEXITCODE -eq 0 -and $branch) { return $branch.Trim() }
+    }
+    return 'unknown'
+}
+
+# Is git available and is this a repository?
+function Test-HasGit {
+    & git rev-parse --show-toplevel *> $null
+    return ($LASTEXITCODE -eq 0)
+}
+
+# Every path a caller needs. Mirrors `get_feature_paths` one key at a time: a caller
+# that reads a key the Bash side emits must find it here too.
+function Get-FeaturePaths {
+    $repoRoot = Get-RepoRoot
+    $specsDir = Join-Path $repoRoot 'specs'
+    # ── Feature-scope detection (FR-063 / T050 · T255, v0.23) ──
+    # cwd inside specs/fNNN-简称/ ⇒ feature scope: spec/plan/tasks/test-tasks resolve
+    # to THAT directory; constitution/research stay mother-side (living-reference
+    # inheritance, FR-014). Greppable anchors: 「feature 作用域」/「母作用域」.
+    # FEATURE_SCOPE is an ASCII value ('true'/'false') — the same decision that keeps
+    # the Bash side safe through eval word-splitting.
+    $scopeDir = [System.IO.Path]::GetFullPath((Get-Location).ProviderPath)
+    $inFeature = 'false'
+    if ($scopeDir -match '/specs/f[0-9][0-9][0-9]-') { $inFeature = 'true' }
+    if ($inFeature -eq 'true') {
+        $fd = $scopeDir
+        $implan = Join-Path $scopeDir 'plan.md'
+        $tasksPath = Join-Path $scopeDir 'tasks.md'
+        $tt = Join-Path $scopeDir 'test-tasks.md'
+    } else {
+        $fd = $specsDir
+        $implan = Join-Path $specsDir 'plan.md'
+        $tasksPath = Join-Path $specsDir 'tasks.md'
+        $tt = Join-Path $specsDir 'test-tasks.md'
+    }
+    [ordered]@{
+        REPO_ROOT     = $repoRoot
+        CURRENT_BRANCH = Get-CurrentBranch
+        HAS_GIT       = if (Test-HasGit) { 'true' } else { 'false' }
+        FEATURE_SCOPE = $inFeature
+        FEATURE_DIR   = $fd
+        FEATURE_SPEC  = Join-Path $fd 'spec.md'
+        IMPL_PLAN     = $implan
+        TASKS         = $tasksPath
+        RESEARCH      = Join-Path $specsDir 'research.md'
+        DATA_MODEL    = Join-Path $specsDir 'data-model.md'
+        QUICKSTART    = Join-Path $specsDir 'quickstart.md'
+        TEST_TASKS    = $tt
+        CONTRACTS_DIR = Join-Path $fd 'contracts'
+    }
+}
+
+# The two status lines the text output mode prints. Same glyphs and same leading
+# spacing as the Bash side — these are read by humans comparing the two outputs.
+function Write-CheckFile {
+    param([string]$Path, [string]$Label)
+    if (Test-Path -LiteralPath $Path -PathType Leaf) { Write-Output "  ✓ $Label" }
+    else { Write-Output "  ✗ $Label" }
+}
+
+function Write-CheckDir {
+    param([string]$Path, [string]$Label)
+    $hasContent = (Test-Path -LiteralPath $Path -PathType Container) -and
+                  ((Get-ChildItem -LiteralPath $Path -Force | Measure-Object).Count -gt 0)
+    if ($hasContent) { Write-Output "  ✓ $Label" }
+    else { Write-Output "  ✗ $Label" }
+}

specpro_cli/assets/scripts/powershell/create-new-feature.ps1

@@ -0,0 +1,229 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Ensure specs/spec.md exists, seeding it from the template, and report the feature number.
+.DESCRIPTION
+    Contract-equivalent to `scripts/bash/create-new-feature.sh`.
+
+    ⚠️ Despite that script's filename and its own header calling it legacy, what it
+    actually does is the **current** layout: it writes `specs/spec.md` directly and
+    creates no branch subdirectory. Its header describes what it used to do. The port
+    follows the behaviour, which is what the callers depend on — see ISS-50.
+
+    Branch names are computed and reported but **do not direct any directory**; every
+    spec file lives directly under specs/.
+
+.EXAMPLE
+    ./create-new-feature.ps1 --json "Add multi-platform install support"
+    ./create-new-feature.ps1 --json --short-name "plugin-arch" --number 7
+#>
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+. (Join-Path $PSScriptRoot 'common.ps1')
+
+$jsonMode = $false
+$shortName = ''
+$branchNumber = ''
+$positional = @()
+
+for ($i = 0; $i -lt $args.Count; $i++) {
+    $arg = $args[$i]
+    switch -Regex ($arg) {
+        '^--?json$' { $jsonMode = $true; continue }
+        '^--?short-name$' {
+            if ($i + 1 -ge $args.Count -or $args[$i + 1] -like '-*') {
+                Write-Error 'Error: --short-name requires a value'
+                exit 1
+            }
+            $shortName = $args[++$i]; continue
+        }
+        '^--?number$' {
+            if ($i + 1 -ge $args.Count -or $args[$i + 1] -like '-*') {
+                Write-Error 'Error: --number requires a value'
+                exit 1
+            }
+            $branchNumber = $args[++$i]; continue
+        }
+        '^--?help$|^-h$' {
+            Write-Output 'Usage: create-new-feature.ps1 [OPTIONS] [FEATURE_DESCRIPTION]'
+            Write-Output '  --json               Output in JSON format'
+            Write-Output '  --short-name NAME    Use NAME as the branch suffix'
+            Write-Output '  --number N           Use N as the feature number'
+            exit 0
+        }
+        default { $positional += $arg; continue }
+    }
+}
+$featureDescription = ($positional -join ' ')
+
+# A description is REQUIRED — the options modify how one is turned into a number and a
+# slug, they do not replace it. Without this check `--short-name x` alone would succeed
+# and produce a branch name with no feature behind it, where the Bash side exits 1.
+if ([string]::IsNullOrEmpty($featureDescription)) {
+    # `$PSCommandPath` is the running script — the ONE intentional difference from the
+    # Bash side, which prints `$0`. Naming the other platform's file would send the
+    # reader looking for something that is not there.
+    [Console]::Error.WriteLine("Usage: scripts/powershell/create-new-feature.ps1 [--json] [--short-name <name>] [--number N] <feature_description>")
+    exit 1
+}
+
+# --- repository root -------------------------------------------------------------------
+# Prefer git; fall back to walking up for a repository marker, so the workflow still
+# functions in repositories initialised with --no-git.
+function Find-RepoRoot {
+    param([string]$Start)
+    $dir = $Start
+    while ($dir -and $dir -ne [System.IO.Path]::GetPathRoot($dir)) {
+        if ((Test-Path (Join-Path $dir '.git')) -or (Test-Path (Join-Path $dir '.specpro'))) {
+            return $dir
+        }
+        $dir = Split-Path $dir -Parent
+    }
+    return $null
+}
+
+if (Test-HasGit) {
+    $repoRoot = (& git rev-parse --show-toplevel).Trim()
+    $hasGit = $true
+} else {
+    $repoRoot = Find-RepoRoot $PSScriptRoot
+    if (-not $repoRoot) {
+        Write-Error 'Error: Could not determine repository root. Please run this script from within the repository.'
+        exit 1
+    }
+    $hasGit = $false
+}
+Set-Location $repoRoot
+$specsDir = Join-Path $repoRoot 'specs'
+New-Item -ItemType Directory -Force -Path $specsDir | Out-Null
+
+# --- numbering helpers -----------------------------------------------------------------
+
+function Get-HighestFromSpecs {
+    param([string]$SpecsDir)
+    $highest = 0
+    if (Test-Path -LiteralPath $SpecsDir -PathType Container) {
+        foreach ($d in Get-ChildItem -LiteralPath $SpecsDir -Directory -Force) {
+            if ($d.Name -match '^([0-9]+)') {
+                # Base-10 explicitly: a leading zero would otherwise read as octal.
+                $n = [int]$Matches[1]
+                if ($n -gt $highest) { $highest = $n }
+            }
+        }
+    }
+    return $highest
+}
+
+function Get-HighestFromBranches {
+    $highest = 0
+    $branches = & git branch -a 2>$null
+    if ($LASTEXITCODE -ne 0 -or -not $branches) { return 0 }
+    foreach ($b in $branches) {
+        $clean = ($b -replace '^[* ]*', '') -replace '^remotes/[^/]+/', ''
+        if ($clean -match '^([0-9]{3})-') {
+            $n = [int]$Matches[1]
+            if ($n -gt $highest) { $highest = $n }
+        }
+    }
+    return $highest
+}
+
+function Get-NextBranchNumber {
+    param([string]$SpecsDir)
+    & git fetch --all --prune *> $null     # failures are expected with no remote
+    $fromBranches = Get-HighestFromBranches
+    $fromSpecs = Get-HighestFromSpecs $SpecsDir
+    return ([Math]::Max($fromBranches, $fromSpecs) + 1)
+}
+
+function Get-CleanBranchName {
+    param([string]$Name)
+    $s = $Name.ToLowerInvariant() -replace '[^a-z0-9]', '-'
+    $s = $s -replace '-+', '-'
+    return $s.Trim('-')
+}
+
+function Get-GeneratedBranchName {
+    param([string]$Description)
+    $stopWords = '^(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)$'
+
+    $words = ($Description.ToLowerInvariant() -replace '[^a-z0-9]', ' ') -split '\s+'
+    $meaningful = @()
+    foreach ($w in $words) {
+        if ([string]::IsNullOrEmpty($w)) { continue }
+        if ($w -match $stopWords) { continue }
+        if ($w.Length -ge 3) { $meaningful += $w; continue }
+        # Short words survive only when the ORIGINAL text has them uppercased — the
+        # usual signal for an acronym the description cares about.
+        #
+        # ⚠️ **This is the one place the two implementations deliberately differ.** The
+        # Bash side writes `${word^^}` for the uppercasing, which is a Bash 4.0+ expansion
+        # — on the Bash 3.2 that macOS ships it fails with "bad substitution", the grep
+        # gets a broken pattern, and the short word is silently dropped. So Bash's output
+        # here is not a contract: it differs between Bash 3.2 and Bash 4+ on the same
+        # input. This side implements the documented INTENT. See ISS-51.
+        if ($Description -cmatch "\b$([regex]::Escape($w.ToUpperInvariant()))\b") { $meaningful += $w }
+    }
+    if ($meaningful.Count -gt 0) {
+        $max = if ($meaningful.Count -eq 4) { 4 } else { 3 }
+        $take = $meaningful | Select-Object -First $max
+        return ($take -join '-')
+    }
+    $cleaned = Get-CleanBranchName $Description
+    $parts = @($cleaned -split '-' | Where-Object { $_ -ne '' } | Select-Object -First 3)
+    return ($parts -join '-')
+}
+
+# --- compose the branch name ------------------------------------------------------------
+$branchSuffix = if ($shortName) { Get-CleanBranchName $shortName } else { Get-GeneratedBranchName $featureDescription }
+
+if (-not $branchNumber) {
+    $branchNumber = if ($hasGit) { Get-NextBranchNumber $specsDir } else { (Get-HighestFromSpecs $specsDir) + 1 }
+}
+$featureNum = '{0:d3}' -f [int]$branchNumber
+$branchName = "$featureNum-$branchSuffix"
+
+# GitHub enforces a 244-byte limit on branch names.
+$maxBranchLength = 244
+if ($branchName.Length -gt $maxBranchLength) {
+    $maxSuffixLength = $maxBranchLength - 4          # number (3) + hyphen (1)
+    $truncated = $branchSuffix.Substring(0, [Math]::Min($maxSuffixLength, $branchSuffix.Length)).TrimEnd('-')
+    $original = $branchName
+    $branchName = "$featureNum-$truncated"
+    [Console]::Error.WriteLine("[specify] Warning: Branch name exceeded GitHub's 244-byte limit")
+    [Console]::Error.WriteLine("[specify] Original: $original ($($original.Length) bytes)")
+    [Console]::Error.WriteLine("[specify] Truncated to: $branchName ($($branchName.Length) bytes)")
+}
+
+# --- produce the spec file --------------------------------------------------------------
+# No Git branch is created for the specification: one project has one spec.md that
+# evolves. Branch information is reported, never used for directory structure.
+$featureDir = $specsDir
+New-Item -ItemType Directory -Force -Path $featureDir | Out-Null
+$specFile = Join-Path $featureDir 'spec.md'
+
+if (-not (Test-Path -LiteralPath $specFile -PathType Leaf)) {
+    $template = Join-Path $repoRoot '.specpro' 'templates' 'spec-template.md'
+    if (Test-Path -LiteralPath $template -PathType Leaf) {
+        Copy-Item -LiteralPath $template -Destination $specFile
+        [Console]::Error.WriteLine("[specify] Created initial specification: $specFile")
+    } else {
+        New-Item -ItemType File -Force -Path $specFile | Out-Null
+        [Console]::Error.WriteLine("[specify] Created empty specification: $specFile")
+    }
+} else {
+    [Console]::Error.WriteLine("[specify] Specification already exists: $specFile")
+    [Console]::Error.WriteLine('[specify] Use /specpro-specify with update intent to evolve the existing spec')
+}
+
+$env:SPECIFY_FEATURE = $branchName
+
+if ($jsonMode) {
+    Write-Output ('{{"BRANCH_NAME":"{0}","SPEC_FILE":"{1}","FEATURE_NUM":"{2}"}}' -f $branchName, $specFile, $featureNum)
+} else {
+    Write-Output "BRANCH_NAME: $branchName"
+    Write-Output "SPEC_FILE: $specFile"
+    Write-Output "FEATURE_NUM: $featureNum"
+    Write-Output "SPECIFY_FEATURE environment variable set to: $branchName"
+}

specpro_cli/assets/scripts/powershell/qc-auto-fix.ps1

@@ -0,0 +1,110 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    QC Auto-Fix — the write-back implementation for `/specpro-qc`.
+.DESCRIPTION
+    Contract-equivalent to `scripts/bash/qc-auto-fix.sh`. The contract is deliberately
+    strong here: **for the same inputs, both implementations print byte-identical output
+    and return the same exit code** (FR-008) — this script is invoked from a command
+    document, and a pair that disagrees across platforms is worse than one that is merely
+    missing, because each side looks authoritative.
+
+    Why this exists (T186 / ISS-143, settled 2026-09-19): these bodies used to live inside
+    `commands/specpro.qc.md` as bash fences. That put an executable implementation in a
+    Markdown document, which the landing policy (`plan.md` -> 落点政策 §1) forbids: an
+    implementation that lives in prose can only be verified by EXTRACTING it, and that
+    extraction depends on the Markdown's shape and returns an empty string — silently —
+    the moment the shape changes. T164 verified its own guard exactly that way.
+
+    What the move must not lose: `apply_fix` is the ONE write-back path, and its value is
+    entirely in three guards added the hard way (T164) —
+
+      1. the destination is a REQUIRED argument (an omitted target ABORTS, it does not
+         guess: a defaulted parameter once delivered the CHECKLIST's content into
+         `spec.md`, observed as a 202-byte spec.md replaced by a 100-byte checklist)
+      2. a non-zero transformer status aborts
+      3. an empty result aborts
+
+      …and then exactly ONE move.
+
+.PARAMETER Command
+    `apply-fix` — and that is the whole surface. ⚠️ Two more subcommands were removed
+    on 2026-09-19 (`ISS-186` / `T220`): the one that rewrote `spec.md` prose, and the
+    one that authorised repairing another command's artifact. The ruling made
+    `/specpro-qc` a checker that **does not repair** (`FR-058`), so there is nothing
+    left for an authorisation guard to guard — see the Bash twin's header for the full
+    reasoning, which is kept in one place on purpose.
+.PARAMETER Args
+    apply-fix:               <tmp> <gen-status> <dest>
+.OUTPUTS
+    Exit 0 = the write happened; 1 = aborted, nothing written.
+#>
+
+param(
+    [Parameter(Position = 0)][string]$Command,
+    [Parameter(Position = 1, ValueFromRemainingArguments = $true)][string[]]$Args
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Write-Usage {
+    # ⚠️ The usage names the COMMAND, not this file — same reason as the Bash twin's note.
+    [Console]::Error.WriteLine('usage: qc-auto-fix apply-fix <tmp> <gen-status> <dest>')
+}
+
+# =======================================================================================
+# Invoke-ApplyFix — the ONE write-back path
+# =======================================================================================
+function Invoke-ApplyFix {
+    param([string]$Tmp, [string]$GenStatus, [string]$Target)
+
+    if ([string]::IsNullOrEmpty($Tmp)) {
+        [Console]::Error.WriteLine('      ✗ fix aborted: no result to write — apply_fix needs a source')
+        return 1
+    }
+
+    if ([string]::IsNullOrEmpty($Target)) {
+        [Console]::Error.WriteLine('      ✗ fix aborted: no destination given — apply_fix does not guess')
+        Remove-Item -Force -ErrorAction SilentlyContinue $Tmp
+        return 1
+    }
+
+    if ([int]$GenStatus -ne 0) {
+        [Console]::Error.WriteLine("      ✗ fix aborted: the transformer exited $GenStatus — $Target left untouched")
+        Remove-Item -Force -ErrorAction SilentlyContinue $Tmp
+        return 1
+    }
+
+    # An empty result is a failure, not a fix: every caller's output is derived from an
+    # input it had to READ, so a zero-byte result means that read failed.
+    if ((-not (Test-Path -LiteralPath $Tmp)) -or ((Get-Item -LiteralPath $Tmp).Length -eq 0)) {
+        [Console]::Error.WriteLine("      ✗ fix aborted: the result is empty — $Target left untouched")
+        Remove-Item -Force -ErrorAction SilentlyContinue $Tmp
+        return 1
+    }
+
+    Move-Item -LiteralPath $Tmp -Destination $Target -Force
+    return 0
+}
+
+# =======================================================================================
+# dispatch
+# =======================================================================================
+# ⚠️ `@($Args)` is NOT empty when no arguments were passed — PowerShell binds one $null
+# element, so `.Count` reads 1 and every arity guard below is skipped. Measured: with the
+# null element left in, `apply-fix` with no arguments fell through to the write-back path
+# and died on an empty path instead of printing the usage the Bash side prints.
+$rest = @($Args | Where-Object { $null -ne $_ -and $_ -ne '' })
+switch ($Command) {
+    'apply-fix' {
+        if ($rest.Count -lt 1) { Write-Usage; exit 1 }
+        $tmp = $rest[0]
+        $gen = if ($rest.Count -ge 2) { $rest[1] } else { '0' }
+        $dest = if ($rest.Count -ge 3) { $rest[2] } else { '' }
+        exit (Invoke-ApplyFix -Tmp $tmp -GenStatus $gen -Target $dest)
+    }
+    default {
+        Write-Usage
+        exit 1
+    }
+}

specpro_cli/assets/scripts/powershell/setup-plan.ps1

@@ -0,0 +1,61 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Prepare the plan artifact for the current project.
+.DESCRIPTION
+    Contract-equivalent to `scripts/bash/setup-plan.sh`: ensure specs/ exists, seed
+    plan.md from the template when it is absent, and report the paths in either JSON or
+    text form.
+
+    As with the other scripts here, arguments are parsed manually so the `--json`
+    spelling used by the Bash side keeps working.
+#>
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+. (Join-Path $PSScriptRoot 'common.ps1')
+
+$jsonMode = $false
+foreach ($arg in $args) {
+    switch -Regex ($arg) {
+        '^--?json$' { $jsonMode = $true; continue }
+        '^--?help$|^-h$' {
+            Write-Output "Usage: setup-plan.ps1 [--json]"
+            Write-Output "  --json    Output results in JSON format"
+            Write-Output "  --help    Show this help message"
+            exit 0
+        }
+        default { continue }   # The Bash side collects unknown args and ignores them.
+    }
+}
+
+$paths = Get-FeaturePaths
+$featureDir = $paths.FEATURE_DIR
+$implPlan = $paths.IMPL_PLAN
+
+New-Item -ItemType Directory -Force -Path $featureDir | Out-Null
+
+$template = Join-Path $paths.REPO_ROOT '.specpro' 'templates' 'plan-template.md'
+
+if (Test-Path -LiteralPath $implPlan -PathType Leaf) {
+    Write-Output "Using existing plan at $implPlan"
+} elseif (Test-Path -LiteralPath $template -PathType Leaf) {
+    Copy-Item -LiteralPath $template -Destination $implPlan
+    Write-Output "Created plan from template at $implPlan"
+} else {
+    Write-Output "Warning: Plan template not found at $template"
+    # Same fallback as the Bash side: leave a file behind so later steps have something
+    # to write into rather than failing on a missing path.
+    New-Item -ItemType File -Force -Path $implPlan | Out-Null
+}
+
+if ($jsonMode) {
+    Write-Output ('{{"FEATURE_SPEC":"{0}","IMPL_PLAN":"{1}","SPECS_DIR":"{2}","BRANCH":"{3}","HAS_GIT":"{4}"}}' -f `
+        $paths.FEATURE_SPEC, $implPlan, $featureDir, $paths.CURRENT_BRANCH, $paths.HAS_GIT)
+} else {
+    Write-Output "FEATURE_SPEC: $($paths.FEATURE_SPEC)"
+    Write-Output "IMPL_PLAN: $implPlan"
+    Write-Output "SPECS_DIR: $featureDir"
+    Write-Output "BRANCH: $($paths.CURRENT_BRANCH)"
+    Write-Output "HAS_GIT: $($paths.HAS_GIT)"
+}