Private/Invoke-CCWorkflowPullRequest.ps1

function Invoke-CCWorkflowPullRequest {
    <#
    .SYNOPSIS
        Converges CodeCompass workflows on a new branch and opens a pull request via gh — so nothing
        lands on the default branch unreviewed. Honours -WhatIf (reports the plan, opens nothing).
    .NOTES
        Requires an authenticated GitHub CLI (gh). Release-local for now; to be extracted to a shared
        PowerShell layer when a second capability needs it.
    #>

    param(
        [Parameter(Mandatory)][string]$Path,
        [string]$Branch = 'codecompass/adopt-release-workflows',
        [Parameter(Mandatory)][System.Management.Automation.PSCmdlet]$Cmdlet
    )

    if (-not (Get-Command gh -ErrorAction SilentlyContinue)) {
        throw "GitHub CLI (gh) is required for -PullRequest. Install gh and run 'gh auth login'."
    }

    $full = (Resolve-Path -LiteralPath $Path).Path
    $service = [CodeCompass.Core.Workflows.WorkflowService]::new()

    # Preview (force + dry-run) — the plan shown under -WhatIf and included in the PR body.
    $plan = $service.Sync($full, 'CodeCompass.Release', $true, $true)
    $summary = ($plan | ForEach-Object { "- {0}: {1}" -f $_.RelativePath, $_.Action }) -join "`n"

    if (-not $Cmdlet.ShouldProcess($full, "Open a pull request ('$Branch') converging CodeCompass workflows")) {
        return [pscustomobject]@{ Branch = $Branch; Action = 'WouldOpenPR'; Plan = $summary }
    }

    Push-Location $full
    try {
        & git rev-parse --is-inside-work-tree *> $null
        if ($LASTEXITCODE -ne 0) { throw "Not a git repository: $full" }

        & git switch -c $Branch
        if ($LASTEXITCODE -ne 0) { throw "Could not create branch '$Branch' (does it already exist?)." }

        $service.Sync($full, 'CodeCompass.Release', $true, $false) | Out-Null

        & git add .github/workflows .codecompass
        & git commit -q -m "Adopt CodeCompass release workflows"
        if ($LASTEXITCODE -ne 0) { throw "git commit failed (nothing to commit?)." }

        & git push -u origin $Branch
        if ($LASTEXITCODE -ne 0) { throw "git push failed for branch '$Branch'." }

        $body = "Adopts CodeCompass-managed release workflows via ``CodeCompass.Release``.`n`n## Changes`n$summary`n`nReview the diff and merge to bring this repo under CodeCompass governance."
        & gh pr create --title "Adopt CodeCompass release workflows" --body $body --head $Branch
    }
    finally {
        Pop-Location
    }
}