Support org-owned fork PR creation without upstream mirroring (#963) (#965)

* #963 Support org-owned fork PR creation without upstream mirroring

* #963 Fix same-owner fork GraphQL metadata query

* #963 Allow explicit issue overrides for fork-aware PR helper

* #963 Hydrate explicit issue PR metadata from GitHub

* #963 Fix leading-dash PR body parsing

---------

Co-authored-by: GitHub Copilot <copilot@users.noreply.github.com>

Author: svelderrainruiz

.github/PR_COMMENT_SNIPPETS.md

@@ -47,7 +47,7 @@ pwsh -File tools/Branch-Orchestrator.ps1 -Issue <number> -Execute -PRTemplate wo
 
 ```text
 pwsh -File tools/New-PullRequestBody.ps1 -Template human-change -Issue <number> -OutputPath pr-body.md
-gh pr create --title "<title>" --body-file pr-body.md
+node tools/npm/run-script.mjs priority:pr -- --issue <number> --repo <owner/repo> --branch <branch> --base <base> --title "<title>" --body-file pr-body.md
 ```
 
 ## Re-run Orchestrated With Same Inputs

AGENTS.md

@@ -170,6 +170,10 @@ line buffers).
   - CLI PR creation should prefer `pwsh -File tools/Branch-Orchestrator.ps1 -Issue <number> -Execute` and switch
     templates with `-PRTemplate workflow-policy|human-change` when the review surface differs from default maintenance
     work.
+  - The lower-level PR helper is `node tools/npm/run-script.mjs priority:pr`; prefer it over raw `gh pr create`
+    because it keeps user forks and same-owner org forks on one deterministic path, including the GraphQL
+    `headRepositoryId` flow when `origin` and `upstream` share the same owner. Pass `--issue <number>` when the branch
+    belongs to a non-standing issue and the helper should not infer intent from the standing-priority cache.
 - Automation-authored PRs must keep the `Agent Metadata` block in the body so reviewer routing remains deterministic.
 - Ensure CI is green (lint + Pester). Verify no lingering processes on self-hosted runners.
 - For `gh issue create` / `gh issue edit` with multiline Markdown bodies in mixed

docs/DEVELOPER_GUIDE.md

@@ -409,8 +409,10 @@ For Docker/Desktop VI history validation, run fast-loop lanes explicitly:
   locally. Add `--observe-only` to mirror staged rollout mode. See `docs/COMMIT_INTEGRITY_CHECK.md` for full contract
   and rollout flags (`COMMIT_INTEGRITY_ENFORCE`).
 - Prefer opening PRs from your fork with `node tools/npm/run-script.mjs priority:pr`; the helper ensures `origin`
-  targets your fork (creating it via `gh repo fork` if needed), pushes the current branch, and calls
-  `gh pr create --title <derived-title> --body <rendered-body> --repo <upstream> --base develop --head <fork>:branch`.
+  targets your fork (creating it via `gh repo fork` if needed), pushes the current branch, and opens the PR through one
+  fork-aware contract. User-owned forks still flow through `gh pr create`; same-owner renamed forks switch to GitHub
+  GraphQL `createPullRequest` with `headRepositoryId` so agents do not need to mirror branches back to upstream just to
+  create the PR.
 - The machine-readable GitHub intake source of truth lives in
   `tools/priority/github-intake-catalog.json`. Use
   `pwsh -File tools/Resolve-GitHubIntakeRoute.ps1 -ListScenarios` or
@@ -419,7 +421,7 @@ For Docker/Desktop VI history validation, run fast-loop lanes explicitly:
 - For the higher-level scenario facade, use
   `pwsh -File tools/New-GitHubIntakeDraft.ps1 -Scenario <name> -OutputPath <body-file>`
   to render the correct issue or PR body from the catalog before invoking
-  `gh issue create` / `gh pr create`. For PR scenarios, the helper can hydrate
+  `gh issue create` / `node tools/npm/run-script.mjs priority:pr`. For PR scenarios, the helper can hydrate
   issue title/URL and standing-priority state from the existing issue snapshot
   under `tests/results/_agent/issue/`.
 - For a machine-readable execution planner and explicit apply helper, use
@@ -431,8 +433,8 @@ For Docker/Desktop VI history validation, run fast-loop lanes explicitly:
   `tests/results/_agent/intake/`.
 - When you need the repository's richer intake metadata blocks and template variants, prefer
   `pwsh -File tools/Branch-Orchestrator.ps1 -Issue <number> -Execute [-PRTemplate <variant>]` or
-  `pwsh -File tools/New-PullRequestBody.ps1 ... -OutputPath pr-body.md` plus `gh pr create --title <title> --body-file
-  pr-body.md`.
+  `pwsh -File tools/New-PullRequestBody.ps1 ... -OutputPath pr-body.md` plus
+  `node tools/npm/run-script.mjs priority:pr -- --issue <number> --repo <owner/repo> --branch <branch> --base <base> --title <title> --body-file pr-body.md`.
 - Detailed enforcement notes (feature-branch guards, merge history workflow,
   merge queue parameters) live in
   [`docs/knowledgebase/FEATURE_BRANCH_POLICY.md`](./knowledgebase/FEATURE_BRANCH_POLICY.md).

docs/documentation-manifest.json

@@ -150,6 +150,7 @@
         "tools/New-GitHubIntakeDraft.ps1",
         "tools/Resolve-GitHubIntakeRoute.ps1",
         "tools/Write-GitHubIntakeAtlas.ps1",
+        "tools/priority/create-pr.mjs",
         "tools/priority/github-intake-catalog.json"
       ]
     },

docs/knowledgebase/GitHub-Intake-Layer.md

@@ -48,7 +48,8 @@ instead of inferring the correct path from prose alone.
 
   For PR scenarios, the draft helper can auto-populate the issue title, issue URL, and standing-priority marker from
   the current issue snapshot under `tests/results/_agent/issue/`, so future agents do not need to restate that context
-  after bootstrap has already synced it.
+  after bootstrap has already synced it. When an explicit issue is outside the standing-priority cache, the helper also
+  falls back to `gh issue view` so non-standing issue PRs still hydrate title/URL cleanly on a fresh clone.
 
 - Default dry-run execution plan:
 
@@ -131,7 +132,7 @@ instead of inferring the correct path from prose alone.
     -IssueTitle "Epic: modernize the GitHub intake layer for future agents" `
     -IssueUrl "https://github.com/LabVIEW-Community-CI-CD/compare-vi-cli-action/issues/875" `
     -Base develop -Branch issue/875-modernize-github-intake-layer -OutputPath pr-body.md
-  gh pr create --title "<title>" --body-file pr-body.md
+  node tools/npm/run-script.mjs priority:pr -- --issue <number> --repo <owner/repo> --branch <branch> --base <base> --title "<title>" --body-file pr-body.md
   ```
 
 - Branch + PR bootstrap:
@@ -141,8 +142,11 @@ instead of inferring the correct path from prose alone.
   ```
 
 The helper script derives the PR title from linked issue metadata when available, falls back to the current branch's
-head commit subject when necessary, and then calls `gh pr create --title ... --body-file ...` with the rendered intake
-document.
+head commit subject when necessary, and then calls `priority:pr` with the rendered intake document. For user-owned
+forks, the helper still routes through `gh pr create`. For same-owner renamed forks, it switches to GitHub GraphQL
+`createPullRequest` with `headRepositoryId` so future agents do not need an upstream-mirror workaround just to open
+the PR. When the branch is tied to a non-standing issue, pass `--issue <number>` so the helper does not need to infer
+intent from the standing-priority cache.
 
 ## Idle Repository Mode
 
@@ -183,8 +187,9 @@ Human-authored PRs should use the `human-change` template so they do not acciden
   reviewer-routing semantics.
 - Use the `human-change` PR template when the PR is not automation-authored and should not carry the agent metadata
   contract.
-- Prefer explicit `--title` plus `--body-file` over `gh pr create --fill`; the title/body contract stays deterministic
-  and avoids GitHub CLI flag conflicts.
+- Prefer `priority:pr` with explicit `--title` plus `--body-file` over raw `gh pr create --fill`; the title/body
+  contract stays deterministic, avoids GitHub CLI flag conflicts, and keeps same-owner fork PR creation on one helper
+  path.
 - Use the wiki as a public portal for discoverability, not as a substitute for checked-in docs.
 - Prefer the checked-in intake catalog plus `Resolve-GitHubIntakeRoute.ps1` when deciding which supported issue or PR
   surface to use.

docs/schemas/github-intake-catalog-v1.schema.json

@@ -16,6 +16,7 @@
           "type": "string",
           "enum": [
             "gh-issue-create",
+            "priority-pr-create",
             "gh-pr-create",
             "branch-orchestrator",
             "open-link"

docs/schemas/github-intake-execution-plan-v1.schema.json

@@ -90,6 +90,7 @@
               "type": "string",
               "enum": [
                 "gh-issue-create",
+                "priority-pr-create",
                 "gh-pr-create",
                 "branch-orchestrator",
                 "open-link"
@@ -234,6 +235,7 @@
           "type": "string",
           "enum": [
             "gh-issue-create",
+            "priority-pr-create",
             "gh-pr-create",
             "branch-orchestrator",
             "open-link"

tests/GitHubIntake.Tests.ps1

@@ -68,11 +68,65 @@ Describe 'GitHubIntake.psm1' {
     $route.targetKey | Should -Be 'human-change'
     $route.targetPath | Should -Be '.github/PULL_REQUEST_TEMPLATE/human-change.md'
     $route.helperPath | Should -Be 'tools/New-GitHubIntakeDraft.ps1'
-    $route.executeCommand | Should -Be 'gh pr create --title "<title>" --body-file pr-body.md'
-    $route.executionKind | Should -Be 'gh-pr-create'
+    $route.executeCommand | Should -Be 'node tools/npm/run-script.mjs priority:pr -- --issue <number> --repo <owner/repo> --branch <branch> --base <base> --title "<title>" --body-file pr-body.md'
+    $route.executionKind | Should -Be 'priority-pr-create'
     $route.execution.branchSource | Should -Be 'current-or-input'
   }
 
+  It 'normalizes legacy gh-pr-create execution kinds to the priority helper contract' {
+    $catalogPath = Join-Path $TestDrive 'github-intake-catalog.json'
+    @'
+{
+  "schema": "github-intake/catalog@v1",
+  "issueTemplates": [],
+  "pullRequestTemplates": [
+    {
+      "key": "human-change",
+      "path": ".github/PULL_REQUEST_TEMPLATE/human-change.md",
+      "templateLabel": "human-change",
+      "metadataMode": "human",
+      "summary": "Human-authored PR template."
+    }
+  ],
+  "contactLinks": [],
+  "routes": [
+    {
+      "scenario": "legacy-human-pr",
+      "routeType": "pull-request-template",
+      "targetKey": "human-change",
+      "helperPath": "tools/New-GitHubIntakeDraft.ps1",
+      "command": "pwsh -File tools/New-GitHubIntakeDraft.ps1 -Scenario legacy-human-pr -OutputPath pr-body.md",
+      "executeCommand": "gh pr create --title \"<title>\" --body-file pr-body.md",
+      "execution": {
+        "kind": "gh-pr-create",
+        "titleSource": "issue-derived",
+        "bodySource": "draft-output",
+        "baseSource": "input-or-default",
+        "branchSource": "current-or-input",
+        "issueSource": "input-or-snapshot"
+      },
+      "summary": "Legacy route."
+    }
+  ]
+}
+'@ | Set-Content -LiteralPath $catalogPath -Encoding utf8
+
+    $previous = $env:COMPAREVI_GITHUB_INTAKE_CATALOG_PATH
+    try {
+      $env:COMPAREVI_GITHUB_INTAKE_CATALOG_PATH = $catalogPath
+      $route = Resolve-GitHubIntakeRoute -Scenario 'legacy-human-pr'
+    } finally {
+      if ($null -eq $previous) {
+        Remove-Item Env:COMPAREVI_GITHUB_INTAKE_CATALOG_PATH -ErrorAction SilentlyContinue
+      } else {
+        $env:COMPAREVI_GITHUB_INTAKE_CATALOG_PATH = $previous
+      }
+    }
+
+    $route.executionKind | Should -Be 'priority-pr-create'
+    $route.execution.kind | Should -Be 'priority-pr-create'
+  }
+
   It 'resolves an issue snapshot from the override directory when present' {
     $snapshotDir = Join-Path $TestDrive 'issue'
     New-Item -ItemType Directory -Path $snapshotDir -Force | Out-Null
@@ -95,6 +149,35 @@ Describe 'GitHubIntake.psm1' {
     $snapshot.title | Should -Be 'Catalog issue'
   }
 
+  It 'falls back to GitHub issue lookup when no local snapshot exists for an explicit issue' {
+    Mock -ModuleName GitHubIntake Resolve-GitHubIssueSnapshotFromGitHub {
+      param([int]$Issue)
+      [pscustomobject]@{
+        number = $Issue
+        title  = 'Live catalog issue'
+        url    = 'https://example.test/issues/963'
+        labels = @('enhancement')
+      }
+    }
+
+    $snapshotDir = Join-Path $TestDrive 'missing-issue-dir'
+    $previous = $env:COMPAREVI_GITHUB_INTAKE_SNAPSHOT_DIR
+    try {
+      $env:COMPAREVI_GITHUB_INTAKE_SNAPSHOT_DIR = $snapshotDir
+      $snapshot = Resolve-GitHubIssueSnapshot -Issue 963
+    } finally {
+      if ($null -eq $previous) {
+        Remove-Item Env:COMPAREVI_GITHUB_INTAKE_SNAPSHOT_DIR -ErrorAction SilentlyContinue
+      } else {
+        $env:COMPAREVI_GITHUB_INTAKE_SNAPSHOT_DIR = $previous
+      }
+    }
+
+    $snapshot.number | Should -Be 963
+    $snapshot.title | Should -Be 'Live catalog issue'
+    Should -Invoke Resolve-GitHubIssueSnapshotFromGitHub -ModuleName GitHubIntake -Times 1 -Exactly
+  }
+
   It 'loads the intake catalog from the override path when present' {
     $catalogPath = Join-Path $TestDrive 'github-intake-catalog.json'
     @'
@@ -184,6 +267,24 @@ Describe 'GitHubIntake.psm1' {
     $context.snapshotResolved | Should -BeTrue
   }
 
+  It 'treats label objects from live snapshots as standing-priority markers' {
+    Mock -ModuleName GitHubIntake Resolve-GitHubIssueSnapshot {
+      [pscustomobject]@{
+        number = 963
+        title  = 'Live GH issue'
+        url    = 'https://example.test/issues/963'
+        labels = @([pscustomobject]@{ name = 'standing-priority' })
+      }
+    }
+
+    $context = Resolve-GitHubIntakeDraftContext -Scenario 'human-pr' -Issue 963 -CurrentBranch 'issue/963-org-owned-fork-pr-helper'
+
+    $context.issueTitle | Should -Be 'Live GH issue'
+    $context.issueUrl | Should -Be 'https://example.test/issues/963'
+    $context.standingPriority | Should -BeTrue
+    $context.snapshotResolved | Should -BeTrue
+  }
+
   It 'preserves a null execute command when the catalog route omits it' {
     $catalogPath = Join-Path $TestDrive 'github-intake-catalog.json'
     @'

tests/Invoke-GitHubIntakeExecutionPlan.Tests.ps1

@@ -73,6 +73,45 @@ Describe 'Invoke-GitHubIntakeExecutionPlan' {
     $state.Invocation.PRTemplate | Should -Be 'workflow-policy'
   }
 
+  It 'dispatches priority-pr-create plans through node after rendering the draft' {
+    $plan = New-GitHubIntakeExecutionPlan `
+      -Scenario human-pr `
+      -Issue 963 `
+      -IssueTitle 'Support org-owned fork PR creation without upstream mirroring' `
+      -Branch 'issue/963-org-owned-fork-pr-helper' `
+      -DraftOutputPath (Join-Path $TestDrive 'pr-body.md')
+
+    $calls = [System.Collections.Generic.List[object]]::new()
+    $result = Invoke-GitHubIntakeExecutionPlan `
+      -Plan $plan `
+      -DraftRenderer {
+        param([hashtable]$DraftParameters)
+        $calls.Add([pscustomobject]@{ kind = 'draft'; outputPath = $DraftParameters.OutputPath; scenario = $DraftParameters.Scenario }) | Out-Null
+        Set-Content -LiteralPath $DraftParameters.OutputPath -Value '# pr draft' -NoNewline
+        return $DraftParameters.OutputPath
+      } `
+      -NativeInvoker {
+        param([string]$FilePath, [string[]]$Arguments)
+        $calls.Add([pscustomobject]@{ kind = 'native'; filePath = $FilePath; arguments = @($Arguments) }) | Out-Null
+        return 'https://example.test/pull/963'
+      }
+
+    $result.executionKind | Should -Be 'priority-pr-create'
+    $result.draftWritten | Should -BeTrue
+    $result.commandFilePath | Should -Be 'node'
+    $calls.Count | Should -Be 2
+    $calls[0].kind | Should -Be 'draft'
+    $calls[1].kind | Should -Be 'native'
+    $calls[1].filePath | Should -Be 'node'
+    $calls[1].arguments | Should -Contain 'tools/npm/run-script.mjs'
+    $calls[1].arguments | Should -Contain 'priority:pr'
+    $calls[1].arguments | Should -Contain '--issue'
+    $calls[1].arguments | Should -Contain '963'
+    $calls[1].arguments | Should -Contain '--branch'
+    $calls[1].arguments | Should -Contain 'issue/963-org-owned-fork-pr-helper'
+    $calls[1].arguments | Should -Contain '--body-file'
+  }
+
   It 'refuses to apply a plan with missing required inputs' {
     $plan = New-GitHubIntakeExecutionPlan -Scenario bug
 

tests/Invoke-GitHubIntakeScenario.Tests.ps1

@@ -45,7 +45,7 @@ Describe 'Invoke-GitHubIntakeScenario.ps1' {
     }
 
     $plan = $json | ConvertFrom-Json -Depth 10
-    $plan.execution.kind | Should -Be 'gh-pr-create'
+    $plan.execution.kind | Should -Be 'priority-pr-create'
     $plan.execution.branch | Should -Be 'issue/923-work'
     $plan.execution.title | Should -Be 'Execution planner issue (#923)'
     $plan.requirements.canApply | Should -BeTrue